API

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.
Image without caption
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.
chat_session_start
A new conversation session is started.
Example
chat_session_message_received
A contact sends a message in a conversation.
Example
chat_session_message_sent
An operator sends a message in a conversation.
Example
chat_session_end
A conversation session ends.
Example
chat_session_unread
A conversation session ends with messages not yet read by an operator.
Example
conversation_ended
A conversation’s status is set to ended.
Example
chat_session_forward
A conversation is assigned to another operator (group).
Example
chat_session_rating
A contact leaves a conversation rating.
Example
chat_session_feedback
A contact leaves feedback on a conversation.
Example
chat_session_survey
A contact answers the survey after a conversation was set to ended.
Example
chat_session_goal
A goal is reached.
Example
operator_online
An operator goes online.
Example
operator_offline
An operator goes offline.
Example
operator_away
An operator goes away.
Example
operator_back
An operator switches from away to online.
Example
um_widget_config
A Widget’s configuration is changed.
Example

Sending conversations to the API

Once you’ve configured the add-on API, you can send conversations to it via the $apicommand or the Action Bar in conversations.
Image without caption
To send multiple conversations to the API, use the bulk action menu under All conversationsin the Message Center.
Image without caption
Once you’ve configured the add-on API, you can send conversations to it via the $api command or the Action Bar in conversations. Sending is now flagged and will be executed as soon as the status of the conversation changes.