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

chatChatObjectInformation about the chat
channel.idStringID of this webhook channel
chatTokenOptional[String]The token you provided when creating a chat
typeStringSee Supported webhook events below


idStringChat ID
human.idStringID of the human
human.nameStringDisplay name of the human

Supported webhook events

Below are the supported events and their specific properties in addition to the common properties above.


messagesArray[MessageObject]List of the new messages added to this chat by bot or agent. See details below.
replyTokenOptional[String]The reply token you provided when sending a message.


typeStringOne of text, media, carousel, hyperlink, thirdparty_agent_takeover
author.typeStringOne of human, bot, agent
author.idStringThe ID of author
author.nameStringThe display name of the author
dataDataObjectDetails about the message

Below is the list of DataObject of different types of messages.

DataObject for text

quickRepliesOptional[Array[QuickReplyObject]]Quick replies suggested by bot


titleStringText to show to human as suggestions
textStringWhen user clicks the quick reply, send this text as a normal text response

DataObject for carousel

cardsArray[CardObject]Maximum length: 10


titleStringCard title
textStringCard description
imageUrlStringCard background image
buttonsArray[ButtonObject]Card buttons. Maximum length: 3


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.
titleStringThe text displayed on the button.
typeStringOne of text, postback, url
textOptional[String]Only for text buttons. The text to send back to Proto.
urlOptional[String]Only for URL Buttons. Opens URLs using browsers or Webview.
isWebviewOptional[Boolean]Only for URL Buttons. Indicates if it should be opened using webview within the chat (if supported).
postbackDataOptional[String]Only for Postback Buttons. The data to be sent back to Proto.

DataObject for media

typeStringOne of image, video, audio, file.
urlStringURL to download the media
filenameStringThe original name of the file

DataObject for hyperlink

labelStringLabel of the hyperlink
urlStringURL of the hyperlink