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`

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`

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`

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`

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`

Name	Type	Description
`label`	String	Label of the hyperlink
`url`	String	URL of the hyperlink

Event format

Common Properties

Supported webhook events

new_messages

DataObject for text

DataObject for carousel

DataObject for media

DataObject for hyperlink

`new_messages`

`DataObject` for `text`

`DataObject` for `carousel`

`DataObject` for `media`

`DataObject` for `hyperlink`