Add-on API Tutorial

Introduction

U kunt Userlike verbinden met uw custom back-end of legacy CRM. Wordt op de hoogte gehouden van interacties met uw bezoekers en klanten, monitor uw operator states en resources met deze callback API addon. Registreer voor een set van events waarvoor u een HTTP POST callback ontvangt naar uw eindpunt.

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.

TypeDescription
chat_sessionDenotes a conversation session.
conversationDenotes a conversation.
um_widgetDenotes a Widget.
operatorDenotes 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.

TypeEventDescription
chat_sessionstartA new conversation session is started.
chat_sessionmessage_receivedA contact sends a message in a conversation.
chat_sessionmessage_sentAn operator sends a message in a conversation.
chat_sessionunreadA conversation session ends with messages not yet read by an operator.
chat_sessionendA conversation session ends.
conversationendedA conversation’s status is set to **ended**.
chat_sessionforwardA conversation is assigned to another operator (group).
chat_sessionratingA contact leaves a conversation rating.
chat_sessionfeedbackA contact leaves feedback on a conversation.
chat_sessionsurveyA contact answers the survey after a conversation was set to **ended**.
chat_sessiongoalA goal is reached.
operatoronlineAn operator goes online.
operatorofflineAn operator goes offline.
operatorawayAn operator goes away.
operatorbackAn operator switches from away to online.
um_widgetconfigA Widget’s configuration is changed.

Code samples

Below you find code samples for each callback.

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_end
A conversation session ends. 
chat_session_unread
A conversation session ends with messages not yet read by an operator. 
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. 
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.