Webhooks
Webhook events will notify you when certain of interactions occur to your bot. For example, when a customer starts a chat, sends a message, or provides feedback.
Webhooks are sent to your server as POST requests. For webhooks, please respond with status code 200 as soon as possible.
Event format
All events will have common properties as metadata that will be required. Each event also has specific properties according to the type of event that it is.
{
"events": [
{
"chat": {
"id": "<CHAT_ID>",
"human": {
"id": "<HUMAN_ID>",
"name": "<Customer's name>"
}
},
"chatToken": "Rb0PU9LqrGnTkWbO4X2Ry33oAQKWJFDnJTrSTA4rcyjfwQ6",
"channel": {
"id": "<CHANNEL_ID>"
},
...
}
]
}
Common Properties
Name | Type | Description |
---|---|---|
chat | ChatObject | Information about the chat |
channel.id | String | ID of this webhook channel |
chatToken | Optional[String] | The token you provided when creating a chat |
type | String | See Supported webhook events below |
ChatObject
Name | Type | Description |
---|---|---|
id | String | Chat ID |
human.id | String | ID of the human |
human.name | String | Display name of the human |
Supported webhook events
Below are the supported events and their specific properties in addition to the common properties above.
new_messages
new_messages
Name | Type | Description |
---|---|---|
messages | Array[MessageObject ] | List of the new messages added to this chat by bot or agent. See details below. |
replyToken | Optional[String] | The reply token you provided when sending a message. |
MessageObject
Name | Type | Description |
---|---|---|
type | String | One of text , media , carousel , hyperlink , thirdparty_agent_takeover |
author.type | String | One of human , bot , agent |
author.id | String | The ID of author |
author.name | String | The display name of the author |
data | DataObject | Details about the message |
Below is the list of DataObject
of different types of messages.
DataObject
for text
DataObject
for text
Name | Type | Description |
---|---|---|
text | String | Text |
quickReplies | Optional[Array[QuickReplyObject ]] | Quick replies suggested by bot |
QuickReplyObject
Name | Type | Description |
---|---|---|
title | String | Text to show to human as suggestions |
text | String | When user clicks the quick reply, send this text as a normal text response |
DataObject
for carousel
DataObject
for carousel
Name | Type | Description |
---|---|---|
cards | Array[CardObject ] | Maximum length: 10 |
CardObject
Name | Type | Description |
---|---|---|
title | String | Card title |
text | String | Card description |
imageUrl | String | Card background image |
buttons | Array[ButtonObject ] | Card buttons. Maximum length: 3 |
ButtonObject
There are three types of buttons in Proto. They behave differently when a user clicks on a button.
- Text Button: Call Send Message API to create a text message.
- Postback Buttons: Call Send Message API to create a button message.
- URL Buttons: Opens URLs using browsers or Webview. There is no need to call Proto API.
Name | Type | Description |
---|---|---|
title | String | The text displayed on the button. |
type | String | One of text , postback , url |
text | Optional[String] | Only for text buttons. The text to send back to Proto. |
url | Optional[String] | Only for URL Buttons. Opens URLs using browsers or Webview. |
isWebview | Optional[Boolean] | Only for URL Buttons. Indicates if it should be opened using webview within the chat (if supported). |
postbackData | Optional[String] | Only for Postback Buttons. The data to be sent back to Proto. |
DataObject
for media
DataObject
for media
Name | Type | Description |
---|---|---|
type | String | One of image , video , audio , file . |
url | String | URL to download the media |
filename | String | The original name of the file |
DataObject
for hyperlink
DataObject
for hyperlink
Name | Type | Description |
---|---|---|
label | String | Label of the hyperlink |
url | String | URL of the hyperlink |
Updated about 1 year ago