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.

Type Description
offline_message Denotes an offline message, the data format is explained in detail in the next paragraphs.
chat_meta Denotes a chat, the data format is explained in detail in the next paragraphs.
chat_widget Denotes a widget, the data format is explained in detail in the next paragraphs.
operator Denotes an Operator state change, the data format is explained in detail in the next paragraphs.
misc Denotes 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.

Type Event Description
offline_message receive Receive a callback for each new offline message you receive.
chat_meta start Receive a callback for each new chat session.
chat_meta forward Receive a callback when a chat session gets forwarded.
chat_meta rating Receive a callback when a chat session receives a rating.
chat_meta feedback Receive a callback when a chat session receives a feedback.
chat_meta survey Receive a callback when a chat session receives a survey.
chat_meta receive Receive a callback when a chat session ends and the conversation is finished.
chat_meta goal Receive a callback when a goal was reached.
chat_widget config Receive a callback when a Chat Widget configuration changes.
operator online Receive a callback when an Operator goes online.
operator offline Receive a callback when an Operator goes offline.
operator away Receive a callback when an Operator goes away.
operator back Receive a callback when an Operator comes back.
misc chatbutler_incoming Receive 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 a 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.