You can use webhooks to integrate your chatbot with a channel that isn't listed in the standard integrations. With a webhook integration, you specify a URL to receive the bot messages from the chatbot, present those messages to your chatbot user, and use the webhook API to send the chatbot user's responses back to your chatbot.
The webhook API can manage the full chatbot channel experience, including starting a chat, sending messages and activity updates, requesting a handover to a livechat agent, and accepting the conversation when it's handed back.
Conversation ID
Each webhook chat has a unique identifier so you can maintain multiple chats from the same integration or pick up where a previous chat left off. For compatibility with other platforms such as Sunshine Conversations, this identifier is called the conversation ID. When working with the webhook API, the conversation ID identifies a specific chat between your chatbot and the webhook integration, not a conversation in the inGenious AI platform.
You'll need to create a webhook integration. The webhook integration page contains the base URL to use for all webhook endpoints and the access token to include as a Bearer token in all requests.
Chatting with webhooks
To use your webhook integration as a custom channel:
- Start a chat:
-
Send a request to tell the chatbot you want to initiate a chat.
The response to this request provides a conversation ID to identify the chat.
This is an identifier of the chat between your chatbot and the webhook integration, it's not related to the conversations in your chatbot.
You'll provide this ID with your future requests so the chatbot knows they're part of the same chat. -
Send a postback to ask the chatbot to start a passage.
You can start the default entry point passage, another entry point, or a specific passage.
-
Send a request to tell the chatbot you want to initiate a chat.
-
Receive messages from the chatbot.
Messages are sent as requests to your webhook endpoint, not as responses to your requests.- Receive a request with a message from the chatbot.
You may also receive an activity update such as a typing indicator, or a request for a hand over. -
Respond to the request with an acknowledgement.
This is not the chatbot user's response, just an acknowledgement that the message was received.
The chatbot waits for each message to be acknowledged before it sends the next.
- Receive a request with a message from the chatbot.
- Send a request with the chat ID and the chatbot user's response to the chatbot.
- Send a message or postback with the chatbot user's response.
You can also send an activity update such as a typing indicator, or request to hand the conversation back from a livechat agent to the chatbot.
- Send a message or postback with the chatbot user's response.
Chats using webhooks follow your chatbot's usual configuration for fallbacks, inactivity, and other chatbot settings.
Webhook endpoints
| Endpoint | Description |
|---|---|
| {baseUrl}/conversations | Initiate a chat and get a conversation ID to identify the chat. |
| {baseUrl}/conversations/{conversationId}/messages | Send a chatbot user message, acknowledge receipt of a chatbot message, or start a specific passage. |
| {baseUrl}/conversations/{conversationId}/delivery | Acknowledge receipt of a chatbot message. |
| {baseUrl}/conversations/{conversationId}/activity | Send chatbot user activity to the chatbot, such as a read receipt or typing indicator. |
| {baseUrl}/conversations/{conversationId}/handback | Hand the chatbot user back to the chatbot from a livechat agent. |
For information on messages and events you'll receive from the chatbot, see Receive chatbot messages.