API Tutorial

Step 1

Go to the Addons section and select the API configure option.

Step 2

Enter the callback URL of your API endpoint. HTTP and HTTPS are supported as protocols. We will POST the data to your URL as JSON document with the content type application json. To configure this addon the callback URL has to be accessible from the internet and needs to return an HTTP 200 code after receiving the POST request.

You will receive the data as a JSON Object via email. If you use the Javascript API to pass your custom data to the chat client it will be included in the "custom" field as an object.

API Callbacks

The calls are grouped into five dedicated formats that are identified by the _type field.

TypeDescription
offline_messageDenotes an offline message, the data format is explained in detail in the next paragraphs.
chat_metaDenotes a chat, the data format is explained in detail in the next paragraphs.
chat_widgetDenotes a widget, the data format is explained in detail in the next paragraphs.
operatorDenotes an Operator state change, the data format is explained in detail in the next paragraphs.
miscDenotes events that do not fit any of the aforementioned formats.

You can configure your addon and subscribe to a set of events that you would like to receive a callback.

TypeEventDescription
offline_messagereceiveReceive a callback for each new offline message you receive.
chat_metastartReceive a callback for each new chat session.
chat_metaforwardReceive a callback when are chat session gets forwarded.
chat_metaratingReceive a callback when a chat session receives a rating.
chat_metafeedbackReceive a callback when a chat session receives a feedback.
chat_metasurveyReceive a callback when a chat session receives a survey.
chat_metareceiveReceive a callback when a chat session ends and the conversation is finished.
chat_metagoalReceive a callback when a goal was reached.
chat_widgetconfigReceive a callback when a Chat Widget configuration changes.
operatoronlineReceive a callback when an Operator goes online.
operatorofflineReceive a callback when an Operator goes offline.
operatorawayReceive a callback when an Operator goes away.
operatorbackReceive a callback when an Operator comes back.
miscchatbutler_incomingReceive a callback when a new chat session is waiting.

Offline Message - Receive

Receive a callback for each new offline message you receive. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Meta - Start

Receive a callback for each new chat session. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Meta - Forward

Receive a callback when are chat session gets forwarded. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Meta - Rating

Receive a callback when a chat session receives a rating. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Meta - Feedback

Receive a callback when a chat session receives a feedback. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Chat Meta - Survey

Receive a callback when a chat session receives a survey. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Meta - Receive

Receive a callback when a chat session ends and the conversation is done. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below. If you used the Javascript API to pass your custom data to the chat client, it will be included in in the "custom" field of the object.

Chat Widget - Config

Receive a callback when a chat widget configuration changes. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Operator - Online

Receive a callback when an operator goes online. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Operator - Offline

Receive a callback when an operator goes offline. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Operator - Away

Receive a callback when an operator goes away. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Operator - Back

Receive a callback when an operator comes back. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Misc - Chat Butler incoming

Receive a callback when a new chat session is waiting. The "POST" callback to your API endpoint will include the data of the object in JSON format. You will find the detailed format in the sample below.

Chat Butler is a simple chatbot that automatically responds to chat requests when no Operator is immediately available, repeatedly notifying your service team that a chat is waiting (full Chat Butler tutorial).

You can integrate these notifications in any of your existing notification frameworks by providing an API endpoint that consumes this callback format.

Sending Offline Messages

After the configuration process you can send your offline messages from the Dashboard to your API.

Sending Chats

The same function is available for sending chat transcripts to your API. You can also trigger the action from a chat session with a chat command.

  • $api - Send current chat to your API.