RTM API Reference
Introduction
Versioning
This document describes the Customer Chat Real-Time Messaging API v3.1. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...
What is RTM API
Real-Time Messaging API (RTM API) is based on a websocket-like connection. Client can send a request message that results in getting a response message. It's also possible to get push messages.
When to use RTM API
If you're wondering which API to use - Customer Chat RTM API or Web API, keep on reading.
Real-Time Messaging API allows for building stateful integrations that require logging in and maintaining the connection. Since connection maintenance is required, the implementation might be more challenging than with Web API.
Customer Chat RTM API enables communication in real time. It supports pushes like sneak peek
, typing indicator
, and other. Web API doesn’t have equivalent webhooks, which means you won't be informed about certain events using Web API.
Also, the RTM API will be a better choice if you want to avoid time delays or presume significant traffic.
Not what you're looking for? Perhaps, you need to use Customer Chat Web API instead.
Access
The basics on authorization and server pinging in the Customer Chat RTM API.
Authorization
Customer authorization is handled with access tokens. Find out how to get an access token from Customer authorization flow. You need to authorize within 30 seconds from establishing the connection. Otherwise, the connection will be closed. Given that the connection is continuosly maintained, you only need to authorize once.
Server pinging
After successful authorization, the client needs to ping the server every 15 seconds. Otherwise, the connection will be closed after about 30 seconds of inactivity. Until authorization is completed, ping is a no-op.
Use one of these 2 ways of pinging the server:
- Protocol message with the ping action
For web applications and backend integrations (e.g. in Python, Go). Send the following request every 15 seconds:
{
"action": "ping",
"payload": {}
}
After pinging the server, the client will receive a response with the ping
action. Thanks to that, the client can make sure the connection is still alive.
- The control frame ping in the websocket protocol
For backend integrations; unavailable in web browsers. Read more about the control frame ping.
Data centers
LiveChat system operates in two data centers: dal
(USA) and fra
(Europe). The default data center is dal
.
For backend applications, you can specify the region in the request header. The mechanism is the same as in Customer Chat Web API reference. It doesn't work for frontend applications, though. Instead, frontend apps connect to a region different than the default one by specifying the region suffix in the URL.
fra
: wss://api-fra.livechatinc.com/v3.1/customer/rtm/ws
dal
: wss://api.livechatinc.com/v3.1/customer/rtm/ws
Events
One of the data structures are events. They are sent to a chat via the send_event
method.
Apart from events, there are also Properties, Users, and Other common data structures.
These are the available event types:
File
File event informs about a file being uploaded.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | |
type | yes | string | file |
properties | no | object | Properties |
url | yes | string | Has to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file . |
Response
Field | Returned | Notes |
---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string . |
type | always | |
author_id | always | |
properties | optionally | |
name | always | |
url | always | |
thumbnail_url , thumbnail2x_url | only for images | |
content_type | always | |
size , width , height | only for images |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
"type": "file",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
"properties": {
// "Properties" object
},
"name": "image25.png", // generated server-side
"url": "https://example.com/image25.png",
"thumbnail_url": "https://example.com/thumbnail.png", // generated server-side
"thumbnail2x_url": "https://example.com/thumbnail2x.png", // generated server-side
"content_type": "image/png", // generated server-side
"size": 123444, // generated server-side
"width": 640, // generated server-side
"height": 480 // generated server-side
}
Filled form
Filled form event contains data from a form (prechat or postchat survey).
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | |
type | yes | string | filled_form |
properties | no | object | Properties |
form_id | yes | string | |
fields | yes | array | The fields a form contains. See filled form fields for details. |
Response
Field | Returned | Notes |
---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string . |
type | always | |
author_id | always | |
properties | optionally | |
form_id | always | |
fields | always | An array of filled form fields |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
"type": "filled_form",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
"properties": {
// "Properties" object
},
"form_id": "1473433500211",
"fields": [{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "John Doe"
}, {
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "customer1@example.com"
}, {
"type": "radio",
"id": "154417206262602571",
"label": "Chat purpose",
"answer": {
"id": "0",
"label": "Support"
}
}, {
"type": "checkbox",
"id": "154417206262604640",
"label": "Company industry",
"answers": [{
"id": "0"
"label": "automotive"
}, {
"id": "1"
"label": "it"
}]
}, {
"type": "group_chooser",
"id": "154417206262605324",
"label": "Choose department",
"answer": {
"group_id": 1,
"label": "Marketing"
}
}]
}
Message
Message event contains text message to other chat users.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | |
text | yes | string | Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages. |
type | yes | string | message |
properties | no | object | Properties |
postback | no | object | Indicates that the message event was generated in response to a rich message event. |
postback.id | yes | string | ID of the postback from the rich message event. |
postback.thread_id | yes | string | ID of the thread with the rich message event. |
postback.event_id | yes | string | ID of the rich message event. |
postback.type | no | string | Should be used together with postback.value (when one of them is present, the other is required). |
postback.value | no | string | Should be used together with postback.type (when one of them is present, the other is required). |
Response
Field | Returned | Notes |
---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string . |
type | always | message |
author_id | always | |
text | always | |
postback | optionally | Appears in a message only when triggered by a rich message. |
postback.id | always | |
postback.thread_id | always | |
postback.event_id | always | |
postback.type | optionally | Appears only if postback.value is present. |
postback.value | optionally | Appears only if postback.type is present. |
properties | optionally | Properties |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
"type": "message",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
"text": "hello there",
"postback": {
"id": "action_call",
"thread_id": "K600PKZON8",
"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
"type": "phone",
"value": "790034890"
},
"properties": {
// "Properties" object
}
}
Rich message
Rich message (RM) event contains a rich message data structure. Read more about rich messages.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | You can give your RM a custom ID. |
type | yes | string | Event type: rich_message |
properties | no | object | The properties data structure |
template_id | yes | string | Defines how every Rich Message will be presented. Values: cards , sticker , or quick_replies . |
elements | no | array | Can contain up to 10 element objects. |
elements.title | yes | string | Displays formatted text on RMs. |
elements.subtitle | yes | string | Displays formatted text on RMs. |
elements.image | yes | image | Displays images on RMs. Required param: url ; Optional params: name , content_type , size , width , height . |
elements.buttons | no | array | Displays buttons. Can contain up to 11 button objects. |
elements.buttons.text | yes | string | Text displayed on a button. |
elements.buttons.type | yes | string | Defines the behavior after a user clicks the button. Should be used together with elements.buttons.value . Possible values: webview , message , url , phone . More... |
elements.buttons.value | yes | string | Should be used together with elements.buttons.type . |
elements.buttons.webview_height | yes | string | Required only for the webview buttontype . Possible values: compact , full , tall . |
elements.buttons.postback_id | yes | string | A description of the sent action. Describes the action sent via send_rich_message_postback . More... |
elements.buttons.user_ids | yes | array | Describes users that sent the postback with "toggled": true . |
Response
Field | Returned | Notes |
---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
author_id | always | Generated server-side |
created_at | always | Date & time format with a resolution of microseconds, UTC string . Generated server-side. |
properties | optionally | |
template_id | always | |
elements | optionally | |
elements.title | always | |
elements.subtitle | always | |
elements.image | always | |
elements.buttons | optionally | |
elements.buttons.text | always | |
elements.buttons.type | always | |
elements.buttons.value | always | |
elements.buttons.webview_height | always | Unless button type is different than webview . |
elements.buttons.postback_id | always | |
elements.buttons.user_ids | always |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "rich_message",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"properties": {
// "Properties" object
},
"template_id": "cards",
"elements": [
{
"title": "Lorem ipsum dolor.",
"subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"image": {
"name": "image25.png",
"url": "https://example.com/image25.png",
"content_type": "image/png",
"size": 123444,
"width": 640,
"height": 480
},
"buttons": [
{
"text": "yes",
"postback_id": "action_yes",
"user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
},
{
"text": "no",
"postback_id": "action_no",
"user_ids": []
},
{
"type": "phone",
"text": "value",
"value": "790034890",
"webview_height": "tall",
"postback_id": "action_call",
"user_ids": []
}
]
}
]
}
Custom
The Custom event is an event with customizable payload.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | You can give the event a custom ID. |
type | yes | string | Event type: custom |
content | no | object | The content you define |
properties | no | object | The properties data structure |
Response
Field | Returned | Notes |
---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
author_id | always | Generated server-side |
created_at | always | Date & time format with a resolution of microseconds, UTC string ; generated server-side |
content | optionally | |
properties | optionally |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "custom",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"content": {
"custom": {
"nested": "json"
}
},
"properties": {
// "Properties" object
}
}
System message
System message event is a native system event sent in specific situations.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
custom_id | no | string | You can give the system message a custom ID. |
type | yes | string | system_message |
text | no | string | Text displayed to recipients |
system_message_type | yes | string | System message type |
text_vars | no | object | Variables used in the text |
Response
Field | Returned | Notes |
---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
created_at | always | Date & time format with a resolution of microseconds, UTC string ; generated server-side |
text | optionally | |
system_message_type | always |
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
"type": "system_message",
"text": "hello there",
"system_message_type": "routing.assigned",
"text_vars": {
"agent": "John Doe"
}
}
Users
Users are another important data structure. Within this data structure type, we can distinguish:
Customer
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"name": "John Smith",
"email": "customer1@example.com",
"avatar": "https://example.com/avatars/1.jpg",
"fields": {
"custom field name": "custom field value"
},
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Field | Req./Opt. | Notes |
---|---|---|
avatar | optional | |
email | optional | |
name | optional | |
fields | optional | |
events_seen_up_to | optional | RFC 3339 datetime string; the timestamp of the most recent event seen by the Customer—all the previous events are considered seen. |
Agent
{
"id": "agent1@example.com",
"type": "agent",
"name": "Support Team",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Other common structures
Apart from Events and Users, there are also other common data structures you might work with. Those are:
Access
{
"access": {
"group_ids": [1, 2]
}
}
Field | Req./Opt. | Note |
---|---|---|
group_ids | required | group 0 means that all agents can see it. |
Chats
{
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"threads": [
// optional
// "Thread" object
],
"threads_summary": [
{
"thread_id": "K600PKZON8",
"order": 129846129847
},
{
"thread_id": "K600PKZON8",
"order": 129846129848
}
],
"properites": {
// "Properites" object
},
"access": {
// "Access" object
},
"is_followed": true
}
Field | Req./Opt. | |
---|---|---|
properties | optional | |
access | optional |
Chat summaries
Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread
object, while Chat summary includes last_thread_summary
and last_event_per_type
.
{
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"last_event_per_type": {
// last event of each type in chat
"message": {
"thread_id": "K600PKZON8",
"thread_order": 3,
"event": {
// "Event > Message" object
}
},
"system_message": {
"thread_id": "K600PKZON6",
"thread_order": 1,
"event": {
// "Event > System message" object
}
}
// ...
},
"last_thread_summary": {
"id": "K600PKZON8",
"order": 3,
"timestamp": 1473433500,
"user_ids": ["agent1@example.com"],
"properites": {
// "Properites" object
},
"tags": ["bug_report"]
},
"properites": {
// "Properites" object
},
"access": {
// "Access" object
},
"is_followed": false
}
Filled form fields
A component of the Filled form event.
Field | Required | Data type | Notes |
---|---|---|---|
fields | yes | array of objects | The fields a form contains. |
type | yes | string | Possible values: checkbox , email , name , question , textarea , group_chooser , radio , select |
id | yes | string | Field id, for all field types |
label | yes | string | Field label; for all field types |
answer | yes | any | For all field types |
answer.id | yes | string | Answer id; for all field types |
answer.label | yes | string | Answer label; for all field types |
answer.group_id | yes | number | For group_chooser |
{
"fields": [{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "John Doe"
}, {
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "customer1@example.com"
}, {
"type": "radio",
"id": "154417206262602571",
"label": "Chat purpose",
"answer": {
"id": "0",
"label": "Support"
}
}, {
"type": "checkbox",
"id": "154417206262604640",
"label": "Company industry",
"answers": [{
"id": "0"
"label": "automotive"
}, {
"id": "1"
"label": "it"
}]
}, {
"type": "group_chooser",
"id": "154417206262605324",
"label": "Choose department",
"answer": {
"group_id": 1,
"label": "Marketing"
}
}]
}
Properties
Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.
{
"properties": {
"rating": {
// <property_namespace>
"score": {
// <property_name>
"value": 1 // <property_value>
},
"comment": {
"value": "rated good!"
}
},
"routing": {
"idle": {
"value": false
}
}
}
}
Threads
{
"id": "K600PKZON8",
"timestamp": 1473433500,
"active": true,
"user_ids": ["agent1@example.com"],
"events": [
// array of "Event" objects
],
"order": 112057129857,
"properties": {
// "Properties" object
},
"access": {
// "Access" object
}
}
Field | Req./Opt. | Note |
---|---|---|
access | optional | |
active | required | Possible values: true (thread is still active) or false (thread no longer active). |
events | optional | |
properties | optional |
Methods
In the websocket transport, actions generate pushes. RTM API actions can also trigger webhooks, but they need to be registered first.
The API endpoint |
---|
wss://api.livechatinc.com/v3.1/customer/rtm/ws |
When connecting to the Customer Chat RTM API, clients have to send over the required query string parameters.
Required parameter | Data type | Notes |
---|---|---|
license_id | integer | LiveChat account ID |
Available methods
GENERAL RTM API REQUEST FORMAT
{
"request_id": "<request_id>", // optional
"action": "<action>",
"payload": {
// optional
}
}
{
"request_id": "<request_id>", // optional
"action": "<action>",
"type": "response",
"success": true,
"payload": {
// optional
}
}
Chats
Get Chats Summary
It returns summaries of the chats a Customer participated in.
Specifics
Action | get_chats_summary |
Web API equivalent | get_chats_summary |
Push message | - |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
offset | No | number | Default: 0; maximum: 100 |
limit | No | number | Default: 10; maximum: 25 |
REQUEST
{
"action": "get_chats_summary",
"payload": {}
}
{
"request_id": "<request_id>", // optional
"action": "get_chats_summary",
"type": "response",
"success": true,
"payload": {
"chats_summary": [
{
"id": "PJ0MRSHTDG",
"order": 1575892853242000,
"last_thread_id": "K600PKZON8",
"last_event_per_type": {
"message": {
"thread_id": "K600PKZON9",
"thread_order": 1,
"event": {
"id": "Q298LUVPRH_1",
"created_at": "2019-12-09T12:01:18.909000Z",
"type": "message",
"text": "hello world",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
}
},
"users": [
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"present": true
},
{
"id": "d5eff798-f8df-4364-8059-649c35c9ed0c",
"name": "Agent Name",
"type": "agent",
"present": true,
"avatar": "https://example.com/avatar.png",
"job_title": "Support Agent"
}
],
"access": {
"group_ids": [0]
},
"properties": {
// "Properties" object
}
},
"active": true
}
],
"total_chats": 1
}
}
Get Chat Threads Summary
Specifics
Action | get_chat_threads_summary |
Web API equivalent | get_chat_threads_summary |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | |
offset | No | number | Default: 0. |
limit | No | number | Default: 25; maximum: 100. |
Response
Field | Notes | |
---|---|---|
threads_summary | Sorted descendingly by order . |
REQUEST
{
"action": "get_chat_threads_summary",
"payload": {
"chat_id": "PJ0MRSHTDG"
}
}
{
"request_id": "<request_id>", // optional
"action": "get_chat_threads_summary",
"type": "response",
"success": true,
"payload": {
"threads_summary": [
{
"id": "Q298LUVPRH",
"order": 1,
"total_events": 1,
"active": true
}
],
"total_threads": 1
}
}
Get Chat Threads
Specifics
Action | get_chat_threads |
Web API equivalent | get_chat_threads |
Push message | - |
Request
Parameter | Required | Data type | |
---|---|---|---|
chat_id | Yes | string | |
thread_ids | Yes | array |
REQUEST
{
"action": "get_chat_threads",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_ids": ["K600PKZON8"]
}
}
{
"request_id": "<request_id>", // optional
"action": "get_chat_threads",
"type": "response",
"success": true,
"payload": {
"chat": {
"id": "PJ0MRSHTDG",
"order": 1576569422,
"threads": [
{
"id": "K600PKZON8",
"active": true,
"user_ids": [
"b7eff798-f8df-4364-8059-649c35c9ed0c",
"bbb67d600796e9f277e360e842418833"
],
"events": [
{
"id": "Q20N9CKRX2_1",
"created_at": "2019-12-17T07:57:41.512000Z",
"type": "message",
"text": "Hello",
"author_id": "bbb67d600796e9f277e360e842418833"
}
],
"order": 1,
"properties": {
// "Property" object
},
"access": {
"group_ids": [0]
}
}
],
"users": [
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"present": true
},
{
"id": "bbb67d600796e9f277e360e842418833",
"name": "Agent Name",
"type": "agent",
"present": true,
"avatar": "https://example.com/avatar.jpg",
"job_title": "Support Agent"
}
],
"access": {
"group_ids": [0]
},
"properties": {
// "Property" object
}
}
}
}
Start Chat
Starts a chat.
Specifics
Action | start_chat |
Web API equivalent | start_chat |
Push message | incoming_chat_thread |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat | No | object | |
chat.properties | No | object | Initial chat properties |
chat.access | No | object | Chat access to set, default: all agents. |
chat.thread | No | object | |
chat.thread.events | No | array | Initial chat events array |
chat.thread.properties | No | object | Initial chat thread properties |
continuous | No | bool | Starts chat as continuous (online group is not required); default: false . |
Response
Field | Data type | Notes |
---|---|---|
chat_id | string | |
thread_id | string | |
event_ids | []string | Returned only when the chat was started with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array. |
REQUEST
{
"action": "start_chat",
"payload": {}
}
{
"request_id": "<request_id>", // optional
"action": "start_chat",
"type": "response",
"success": true,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "PGDGHT5G"
}
}
Activate Chat
Used to restart an archived chat.
Specifics
Action | activate_chat |
Web API equivalent | activate_chat |
Push message | incoming_chat_thread |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
chat | Yes | object | |
chat.id | Yes | string | The ID of the chat that will be activated. |
chat.access | No | object | Chat access to set, default: all agents. |
chat.properties | No | object | Initial chat properties |
chat.thread | No | object | |
chat.thread.events | No | array | Initial chat events array |
chat.thread.properties | No | object | Initial chat thread properties |
continuous | No | bool | Sets a chat to the continuous mode. When unset, leaves the mode unchanged. |
Response
Field | Data type | Notes |
---|---|---|
thread_id | string | |
event_ids | []string | Returned only when the chat was activated with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array. |
REQUEST
{
"action": "activate_chat",
"payload": {
"chat": {
"id": "PWJ8Y4THAV"
}
}
}
{
"request_id": "<request_id>", // optional
"action": "activate_chat",
"type": "response",
"success": true,
"payload": {
"thread_id": "Z8AGR5OUW"
}
}
Close Thread
Closes the thread. Sending messages to this thread will no longer be possible.
Specifics
Action | close_thread |
Web API equivalent | close_thread |
Push message | incoming_event and thread_closed |
Request
Parameter | Required | Data type | |
---|---|---|---|
chat_id | Yes | string |
REQUEST
{
"action": "close_thread",
"payload": {
"chat_id": "PJ0MRSHTDG"
}
}
{
"request_id": "<request_id>", // optional
"action": "close_thread",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Events
Send Event
Sends an Event object. Use this method to send a message by specifing the Message event type in the request.
Specifics
Action | send_event |
Web API equivalent | send_event |
Push message | incoming_event |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to send the message to. |
event | Yes | object | The Event object |
attach_to_last_thread | No | bool | The flag is ignored for active chats. For inactive chats: true – the event will be added to the last thread; false – the request will fail. Default: false . |
REQUEST
{
"action": "send_event",
"payload": {
"chat_id": "PW94SJTGW6",
"event": {
"type": "message",
"text": "hello world",
"recipients": "all"
}
}
}
{
"request_id": "<request_id>", // optional
"action": "send_event",
"type": "response",
"success": true,
"payload": {
"event_id": "K600PKZON8"
}
}
Send Rich Message Postback
Specifics
Action | send_rich_message_postback |
Web API equivalent | send_rich_message_postback |
Push message | incoming_rich_message_postback * |
*) incoming_rich_message_postback
will be sent only for active threads.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | |
event_id | Yes | string | |
postback | Yes | object | |
postback.id | Yes | string | Postback name of the button |
postback.toggled | Yes | bool | Postback toggled, true or false |
thread_id | Yes | string |
REQUEST
{
"action": "send_rich_message_postback",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
"postback": {
"id": "Method URL_yes",
"toggled": true
}
}
}
{
"request_id": "<request_id>", // optional
"action": "send_rich_message_postback",
"type": "response",
"success": true,
"payload": {
//no response payload
}
}
Send Sneak Peek
Sends a sneak peek to a chat.
Specifics
Action | send_sneak_peek |
Web API equivalent | send_sneak_peek |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat to send a sneak peek to. |
sneak_peek_text | Yes | string | Sneak peek text |
REQUEST
{
"action": "send_sneak_peek",
"payload": {
"chat_id": "PJ0MRSHTDG",
"sneak_peek_text": "hello world"
}
}
{
"request_id": "<request_id>", // optional
"action": "send_sneak_peek",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Properties
Update Chat Properties
Specifics
Action | update_chat_properties |
Web API equivalent | update_chat_properties |
Push message | chat_properties_updated |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you to set a property for. |
properties | Yes | object | Chat properties to set. You should stick to the general properties format and include namespace, property name and value. |
REQUEST
{
"action": "update_chat_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}
}
{
"request_id": "<request_id>", // optional
"action": "update_chat_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Delete Chat Properties
Specifics
Action | delete_chat_properties |
Web API equivalent | delete_chat_properties |
Push message | chat_properties_deleted |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to delete properties of. |
properties | Yes | object | Chat properties to delete. |
REQUEST
{
"action": "delete_chat_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
}
}
}
{
"request_id": "<request_id>", // optional
"action": "delete_chat_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Update Chat Thread Properties
Specifics
Action | update_chat_thread_properties |
Web API equivalent | update_chat_thread_properties |
Push message | chat_thread_properties_updated |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to set properties for. |
thread_id | Yes | string | Id of the thread you want to set properties for. |
properties | Yes | object | Chat properties to set. You should stick to the general properties format and include namespace, property name and value. |
REQUEST
{
"action": "update_chat_thread_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}
}
{
"request_id": "<request_id>", // optional
"action": "update_chat_thread_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Delete Chat Thread Properties
Specifics
Action | delete_chat_thread_properties |
Web API equivalent | delete_chat_thread_properties |
Push message | chat_thread_properties_deleted |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to delete the properties of. |
thread_id | Yes | string | Id of the thread you want to delete the properties of. |
properties | Yes | object | Chat thread properties to delete. |
REQUEST
{
"action": "delete_chat_thread_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
}
}
}
{
"request_id": "<request_id>", // optional
"action": "delete_chat_thread_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Update Event Properties
Specifics
Action | update_event_properties |
Web API equivalent | update_event_properties |
Push message | event_properties_updated |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to set properties for. |
thread_id | Yes | string | Id of the thread you want to set properties for. |
event_id | Yes | string | Id of the event you want to set properties for. |
properties | Yes | object | Chat properties to set. You should stick to the general properties format and include namespace, property name and value. |
REQUEST
{
"action": "update_event_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"event_id": "2_EW2WQSA8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}
}
{
"request_id": "<request_id>", // optional
"action": "update_event_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Delete Event Properties
Specifics
Action | delete_event_properties |
Web API equivalent | delete_event_properties |
Push message | event_properties_deleted |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | Id of the chat you want to delete the properties of. |
thread_id | Yes | string | Id of the thread you want to delete the properties of. |
event_id | Yes | string | Id of the event you want to delete the properties of. |
properties | Yes | object | Event properties to delete. |
REQUEST
{
"action": "delete_event_properties",
"payload": {
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"event_id": "2_EW2WQSA8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"rating": ["score", "comment"]
}
}
}
}
{
"request_id": "<request_id>", // optional
"action": "delete_event_properties",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Customers
Update Customer
Specifics
Action | update_customer |
Web API equivalent | update_customer |
Push message | customer_updated |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
name | No | string | |
email | No | string | |
avatar | No | string | URL of the Customer's avatar. |
fields | No | object | key: value format |
At least one optional parameter needs to be included in the request payload.
REQUEST
{
"action": "update_customer",
"payload": {
"name": "John Doe"
}
}
{
"request_id": "<request_id>", // optional
"action": "update_customer",
"type": "response",
"success": true,
"payload": {
// "User > Customer" object
}
}
Update Customer Page
Specifics
Action | update_customer_page |
Web API equivalent | - |
Push message | customer_page_updated |
Agent and referrer are updated by default using the browser’s headers.
Request
Parameter | Required | Data type | |
---|---|---|---|
url | Yes | string | |
title | No | string |
REQUEST
{
"action": "update_customer_page",
"payload": {
"url": "https://livechatinc.com/pricing"
}
}
{
"request_id": "<request_id>", // optional
"action": "update_customer_page",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Set Customer Fields
Specifics
Action | set_customer_fields |
Web API equivalent | set_customer_fields |
Push message | customer_updated |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
fields | Yes | object | key:value format |
Agent and referrer are updated by default using the browser’s headers.
REQUEST
{
"action": "set_customer_fields",
"payload": {
"fields": {
"company_size": "10-100"
}
}
}
{
"request_id": "<request_id>", // optional
"action": "set_customer_fields",
"type": "response",
"success": true,
"payload": {
// no response payload
}
}
Status
Login
It returns the initial state of the current Customer.
Specifics
Action | login |
Web API equivalent | - |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
token | Yes | string | OAuth token from the Customer's account |
customer | No | object | |
customer.avatar | No | string | The URL of the Customer's avatar |
customer.email | No | string | |
customer.name | No | string | |
customer.fields | No | object | A map in the "key": "value" format |
customer_page.title | No | string | |
customer_page.url | No | string | |
customer_side_storage * | No | object | A map in the "key": "value" format |
is_mobile | No | bool | Informs if logging in is performed from a mobile device. |
group_id | No | number | |
referrer | No | string |
*) We use customer_side_storage
to keep some data on the client side. You should pass a map from the customer_side_storage_updated
push payload to this field.
REQUEST
{
"action": "login",
"payload": {
"token": "<customer_access_token>"
}
}
}
{
"request_id": "<request_id>", // optional
"action": "login",
"type": "response",
"success": true,
"payload": {
"customer_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
"has_active_thread": true,
"chats": [{
"chat_id": "PJ0MRSHTDG",
"has_unread_events": true
}],
"__priv_dynamic_config": {
"customer_data": {
"name": "John Doe",
"last_visit_timestamp": 1473433500,
"page_views_count": 40,
"visits_count": 15,
"chats_count": 2,
"invitations_shown_count": 20,
"invitations_accepted_count": 1,
"client_version": "432423423",
"fields": "some fields",
"group_id": 2
},
"online_groups_ids": [1, 3],
"global_properties": {
"key1": "value1",
"key2": "value2"
},
"customer_groups": {
"monitoring": {
"id": 1,
"static_config_url": "/licence/1520/get_static_config.121.1808829.94.95.39446.4011.2385.398.160.552.58.337.44320.js",
"language_config_url": "/licence/1520/v2/localization.en.121.004b8e014f50ea0c6ad6227162f7d18f_40d391a9adcdbf190e62fcd21c865bf2.js"
},
"chats": {
"2": {
"chat_ids": ["PJ0MRSHTDG"],
"static_config_url": "/licence/1520/get_static_config.121.1808829.94.95.39446.4011.2385.398.160.552.58.337.44320.js",
"language_config_url": "/licence/1520/v2/localization.en.121.004b8e014f50ea0c6ad6227162f7d18f_40d391a9adcdbf190e62fcd21c865bf2.js"
}
}
},
"static_config_version": "3435.4545",
"predicted_agent": {
"id": "agent1@example.com",
"name": "Bart",
"type": "agent",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"job_title": "Support Agent"
},
"greeting": {
"id": 342543723,
"unique_id": "e35a4fb4106d87e550fe1af480639058",
"text": "some message",
"agent": {
"id": "agent1@example.com",
"name": "Bart",
"type": "agent",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"job_title": "Support Agent",
"is_bot": false
},
"displayed_first_time": true
}
}
}
}
Get Groups Status
Specifics
Action | get_groups_status |
Web API equivalent | get_groups_status |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
all | No | bool | If set to true , you will get statuses of all the groups. |
groups | No | array | A table of a groups' IDs |
One of the optional parameters needs to be included in the request payload.
Response
Group Not Found | If you send group_id of a group that doesn't exists, the id won't be included in the resposne payload. |
REQUEST
{
"action": "get_groups_status",
"payload": {
"all": true
}
}
{
"request_id": "<request_id>", // optional
"action": "get_groups_status",
"type": "response",
"success": true,
"payload": {
"groups_status": {
//1,2,3 are group ids, online/offline/online_for_queue are statuses of the groups
1: "online",
2: "offline",
3: "online_for_queue"
}
}
}
Other
Get Form
Returns an empty ticket form of a prechat or postchat survey.
Specifics
Action | get_form |
Web API equivalent | get_form |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
group_id | Yes | number | Id of the group from which you want the form. |
type | Yes | string | Form type. Possible values: prechat or postchat . |
Response
Field | Notes |
---|---|
enabled | If enabled: false , the form object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI. |
form | The form object |
REQUEST
{
"action": "get_form",
"payload": {
"group_id": 0,
"type": "prechat"
}
}
{
"payload": {
"form": {
"id": "156630109416307809",
"fields": [
{
"id": "15663010941630615",
"type": "header",
"label": "Welcome to our LiveChat! Please fill in the form below before starting the chat."
},
{
"id": "156630109416307759",
"type": "name",
"label": "Name:",
"required": false
},
{
"id": "15663010941630515",
"type": "email",
"label": "E-mail:",
"required": false
}
]
},
"enabled": true
}
}
Get Predicted Agent
Gets the predicted Agent - the one the Customer will chat with when the chat starts.
Specifics
Action | get_predicted_agent |
Web API equivalent | get_predicted_agent |
Push message | - |
REQUEST
{
"action": "get_predicted_agent",
"payload": {}
}
{
"request_id": "<request_id>", // optional
"action": "get_predicted_agent",
"type": "response",
"success": true,
"payload": {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"name": "Name",
"avatar": "https://example.avatar/example.com",
"is_bot": false,
"job_title": "support hero",
"type": "agent"
}
}
Get URL Details
It returns the info on a given URL.
Specifics
Action | get_url_details |
Web API equivalent | get_url_details |
Push message | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
url | Yes | string | Valid website URL |
REQUEST
{
"action": "get_url_details",
"payload": {
"url": "https://livechatinc.com"
}
}
{
"request_id": "<request_id>", // optional
"action": "get_url_details",
"type": "response",
"success": true,
"payload": {
"title": "LiveChat | Live Chat Software and Help Desk Software",
"description": "LiveChat - premium live chat software and help desk software for business. Over 24 000 companies from 150 countries use LiveChat. Try now, chat for free!",
"image_url": "s3.eu-central-1.amazonaws.com/labs-fraa-livechat-thumbnails/96979c3552cf3fa4ae326086a3048d9354c27324.png",
"image_width": 200,
"image_height": 200,
"url": "https://livechatinc.com"
}
}
Mark Events As Seen
Specifics
Action | mark_events_as_seen |
Web API equivalent | mark_events_as_seen |
Push message | events_marked_as_seen |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
chat_id | Yes | string | |
seen_up_to | Yes | string | RFC 3339 date-time format |
Response
No response payload (200 OK
).
REQUEST
{
"action": "mark_events_as_seen",
"payload": {
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
}
}
Pushes
Here's what you need to know about pushes:
- They are generated primarily by RTM API actions, but also by Web API actions.
- They notify you when specific events occur.
- Can be delivered only in the websocket transport.
- You don't need to register pushes to receive them.
- Their equivalents in Web API are webhooks. Pushes and webhooks have similar payloads.
- There are no retries for pushes. To determine if a customer has seen an event, compare the event's
created_at
parameter with the customer'sevents_seen_up_to
field.
{
"request_id": "<request_id>", // optional, applies only to the requester
"action": "<action>",
"type": "push",
"payload": {
// optional payload
}
}
Chats
incoming_chat_thread
Informs about a new thread coming in the chat. The push payload contains not only the new thread, but the whole chat data structure. If the chat was started with some initial events, the thread object contains them.
{
"chat": {
"id": "PJ0MRSHTDG",
"order": 343544565,
"users": [
// array of "User" objects
],
"properties": {
// "Properties" object
},
"access": {
// "Access" object
},
"thread": {
// "Thread" object
}
}
}
Specifics
Action | incoming_chat_thread |
Webhook equivalent | incoming_chat_thread |
thread_closed
Informs that a thread was closed.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
}
Specifics
Action | thread_closed |
Webhook equivalent | thread_closed |
Push payload
Field | Notes |
---|---|
user_id | Missing if a thread was closed by the router. |
Chat access
access_set
Informs that new, single access to a resource was set. The existing access is overwritten.
{
"resource": "chat",
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
}
Specifics
Action | access_set |
Webhook equivalent | access_set |
Push payload
Field | Notes |
---|---|
resource | Resource type |
id | Resource id |
chat_transferred
Informs that a chat was transferred to a different group or to an Agent.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"requester_id": "cb531744-e6a4-4ded-b3eb-b3eb4ded4ded",
"type": "agent",
"ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
}
Specifics
Action | chat_transferred |
Webhook equivalent | - |
Push payload
Field | Notes |
---|---|
type | agent or group |
ids | An array of the group or agent IDs |
Chat users
chat_user_added
Informs that a user (Customer or Agent) was added to a chat.
This push can be emitted with user.present
set to false
when a user writes to a chat without joining it. You can achieve that via the Send Event method.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user": {
// "User > Customer" or "User > Agent" object
},
"user_type": "customer"
}
Specifics
Action | chat_user_added |
Webhook equivalent | chat_user_added |
Push payload
Field | Notes |
---|---|
user_type | Possible values: agent , customer |
thread_id | Empty if a user was added to an inactive chat. |
chat_user_removed
Informs that a user (Customer or Agent) was removed from a chat.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "user@example.com",
"user_type": "customer"
}
Specifics
Action | chat_user_removed |
Webhook equivalent | chat_user_removed |
Push payload
Field | Notes |
---|---|
user_type | Possible values: agent , customer |
thread_id | Empty if a user was removed from an inactive chat. |
Events
incoming_event
Informs about an incoming event sent to a chat.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event": {
"id": "Q20163UAHO_2",
"created_at": "2019-12-05T07:27:08.820000Z",
"recipients": "all",
"type": "message",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": {
"value": "string value"
}
}
},
"text": "Hello",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
}
Specifics
Action | incoming_event |
Webhook equivalent | incoming_event |
event_updated
Informs that an event was updated.
{
"chat_id": "123-123-123-123",
"thread_id": "E2WDHA8A",
"event": {
// "Event" object
}
}
Specifics
Action | event_updated |
Webhook equivalent | event_updated |
incoming_rich_message_postback
Informs about an incoming rich message postback. The push payload contains the info on the postback itself, as well as the chat it was sent in.
{
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
"postback": {
"id": "action_yes",
"toggled": true
}
}
Specifics
Action | incoming_rich_message_postback |
Webhook equivalent | incoming_rich_message_postback |
Properties
chat_properties_updated
Informs about those chat properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": {
"score": {
"value": 1
},
"comment": {
"value": "Very good!"
}
}
// ...
}
}
Specifics
Action | chat_properties_updated |
Webhook equivalent | chat_properties_updated |
Push payload
Field | Notes |
---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
chat_properties_deleted
Informs about those chat properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
}
Specifics
Action | chat_properties_deleted |
Webhook equivalent | chat_properties_deleted |
Push payload
Field | Notes |
---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
chat_thread_properties_updated
Informs about those chat thread properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": {
"value": {
"value": 1
},
"comment": {
"value": "Very good!"
}
}
// ...
}
}
Specifics
Action | chat_thread_properties_updated |
Webhook equivalent | chat_thread_properties_updated |
Push payload
Field | Notes |
---|---|
properties | This is not a full properties object. This push shows only the properties the have been recently updated. |
chat_thread_properties_deleted
Informs about those chat thread properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
}
Specifics
Action | chat_thread_properties_deleted |
Webhook equivalent | chat_thread_properties_deleted |
Push payload
Field | Notes |
---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
event_properties_updated
Informs about those event properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "2_E2WDHA8A",
"properties": {
"rating": {
"comment": {
"value": "Very good!"
}
}
}
}
Specifics
Action | event_properties_updated |
Webhook equivalent | event_properties_updated |
Push payload
Field | Notes |
---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
event_properties_deleted
Informs about those event properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "2_E2WDHA8A",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
}
Specifics
Action | event_properties_deleted |
Webhook equivalent | event_properties_deleted |
Push payload
Field | Notes |
---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
Customers
customer_updated
Informs that Customer's data was updated.
{
"customer": {
// "User > Customer" object
}
}
Specifics
Action | customer_updated |
Webhook equivalent | - |
customer_page_updated
Informs that a Customer changed the website - moved to another page of the website, for example by clicking on a link.
{
"url": "https://livechatinc.com/pricing",
"title": "pricing",
"timestamp": 123456789
}
Specifics
Action | customer_page_updated |
Webhook equivalent | - |
customer_side_storage_updated
Informs that a Customer updated the data stored on their side.
{
"customer_side_storage": {
"customer_visits": "1"
}
}
Specifics
Action | customer_side_storage_updated |
Webhook equivalent | - |
Push payload
Field | Notes |
---|---|
customer_side_storage | A map in the key : value format. Map content should be kept on the client side (e.g. in browsers local storages) and sent via login . |
Status
customer_disconnected
Informs that a Customer was disconnected. The payload contains the reason of Customer's disconnection.
{
"reason": "misdirected_connection",
"data": {
// optional
"region": "fra"
}
}
Specifics
Action | customer_disconnected |
Webhook equivalent | - |
Push payload
Field | Notes |
---|---|
reason |
Possible reasons
Type | Notes |
---|---|
access_token_expired | Access token lifetime has elapsed. |
connection_timeout | Has not received ping from the client for some time, or it's been too long since the connection was authorized. |
customer_banned | Customer has been banned. |
customer_temporarily_blocked * | Customer tried reconnecting too many times after the too_many_connections error had occurred. |
inactivity_timeout | Customer didn't chat or change the page in the past 30 minutes. |
internal_error | Internal, unexpected error; reconnecting is advised |
license_not_found | The license with the specified ID doesn't exist. |
license_expired | The license has expired. |
misdirected_connection ** | Customer connected to a server in the wrong region. |
product_version_changed | The product version has changed. |
service_temporarily_unavailable | The Customer Chat API should be available again soon; reconnecting is advised |
too_many_connections | Customer has reached the maximum number of connections. |
too_many_unauthorized_connections | The maximum number of unauthorized connections has been reached. |
unsupported_version | Connecting to an unsupported version of the Customer Chat API. |
*)
The misdirected_connection
reason can also return the correct region in an optional data object. With this piece of information, client is able to figure out where it should be connected.
**)
The customer_temporarily_blocked
reason can also return the correct timeout in an optional data object. With this piece of information, client is able to figure out how much time a customer should wait before attempting to reconnect again.
Other
incoming_typing_indicator
Informs that one of the chat users is currently typing a message. The message hasn't been sent yet. The push payload contains the typing indicator object.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"typing_indicator": {
"author_id": "d17cd570-11a9-45c0-45c0-1b020b7586dc",
"recipients": "all",
"timestamp": 1574245378,
"is_typing": true
}
}
Specifics
Action | incoming_typing_indicator |
Webhook equivalent | - |
incoming_multicast
Informs about messages sent via the multicast
method or by the system.
{
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"content": {
"example": {
"nested": "json"
}
}
}
Specifics
Action | incoming_multicast |
Webhook equivalent | - |
Push payload
Field | Required | Notes |
---|---|---|
author_id | No | Present only if the push was generated by the Multicast method and not sent from the server. |
content | Yes |
events_marked_as_seen
Informs that a user has seen events up to a specific time.
{
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Specifics
Action | events_marked_as_seen |
Webhook equivalent | events_marked_as_seen |
Errors
{
"error": {
"type": "misdirected_request",
"message": "Wrong region",
"data": {
// optional
"region": "dal"
}
}
}
Possible errors
Error type | Default message | Description |
---|---|---|
authentication | Authentication error | An invalid or expired access token. |
authorization | Authorization error | User is not allowed to perform the action. |
customer_banned | Customer is banned | The customer had been banned. |
greeting_not_found | Greeting not found | |
group_not_found | Group not found | |
group_offline | Group is offline | Thrown in response to Get Predicted Agent. |
group_unavailable | No agent available for group | Thrown in response to Get Predicted Agent. The group is online, but there are no available Agents. |
groups_offline | Groups offline | |
internal | Internal server error | |
license_expired | License expired | The end of license trial or subcription. |
pending_requests_limit_reached | Requests limit reached | The limit of pending requests within one websocket connection has been reached. The limit is 10. |
request_timeout | Request timed out | Timeout threshold is 15 seconds. |
too_many_requests | Too many requests | The request's rate limit was exceeded. It'll be unblocked automatically after some time. |
unsupported_version | Unsupported version | Unsupported protocol version. |
users_limit_reached | Users limit reached | Displayed on the attempt of logging in. The limit of online Customers for a given license has been reached. |
validation | Wrong format of request | |
wrong_product_version | Wrong product version | License is not LiveChat 3 (probably still LiveChat 2). |
Contact us
If you found a bug or a typo, you can let us know directly on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@livechat.com. We'll be happy to hear from you!