Add-on API Tutorial
Step 1
Go to the **Add-ons** section and select API.
Step 2
In the add-on settings, enter the callback URL of your API endpoint. HTTP and HTTPS are supported as protocols. We will POST the data to your URL as a JSON document with the content type `application/JSON`. The callback URL you enter has to be accessible and needs to return an HTTP 200 code after receiving the POST request.
If you use the JavaScript API to pass custom data to the Website Messenger (Widget), it will be included in the request we make to your endpoint as an object in the `custom` field.
API callbacks
The calls are grouped into five dedicated formats that are identified by the `_type` field. The data formats are explained in detail further below.
| Type | Description |
|---|---|
chat_session
|
Denotes a conversation session. |
conversation
|
Denotes a conversation. |
um_widget
|
Denotes a Widget. |
operator
|
Denotes an operator state change. |
You can configure your add-on and subscribe to a set of events that you would like to receive a callback for.
| Type | Event | Description |
|---|---|---|
chat_session
|
start
|
A new conversation session is started. |
chat_session
|
message_received
|
A contact sends a message in a conversation. |
chat_session
|
message_sent
|
An operator sends a message in a conversation. |
chat_session
|
unread
|
A conversation session ends with messages not yet read by an operator. |
chat_session
|
end
|
A conversation session ends. |
conversation
|
ended
|
A conversation’s status is set to **ended**. |
chat_session
|
forward
|
A conversation is assigned to another operator (group). |
chat_session
|
rating
|
A contact leaves a conversation rating. |
chat_session
|
feedback
|
A contact leaves feedback on a conversation. |
chat_session
|
survey
|
A contact answers the survey after a conversation was set to **ended**. |
chat_session
|
goal
|
A goal is reached. |
operator
|
online
|
An operator goes online. |
operator
|
offline
|
An operator goes offline. |
operator
|
away
|
An operator goes away. |
operator
|
back
|
An operator switches from away to online. |
um_widget
|
config
|
A Widget’s configuration is changed. |
Code samples
Below you find code samples for each callback.
Sending conversations to the API
Once you’ve configured the add-on API, you can send conversations to it via the **$api** command or the Action Bar in conversations.
To send multiple conversations to the API, use the bulk action menu under **All conversations** in the Message Center.
