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