API version

RTM API Reference

7 minutes reading time

Introduction

Versioning

This document describes the Customer Chat Real-Time Messaging API v3.2. This is the latest stable version recommended for the production use. 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.2/customer/rtm/ws

dal: wss://api.livechatinc.com/v3.2/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

The File event informs about an uploaded file.

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfile
propertiesnoobjectProperties
urlyesstringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
namealways
urlalways
thumbnail_url, thumbnail2x_urlonly for images
content_typealways
size, width, heightonly for images
Sample File in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"type": "file",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"name": "image25.png",
	"url": "https://example.com/image25.png",
	"thumbnail_url": "https://example.com/thumbnail.png",
	"thumbnail2x_url": "https://example.com/thumbnail2x.png",
	"content_type": "image/png",
	"size": 123444,
	"width": 640,
	"height": 480
}

Filled form

The Filled form event contains data from a form (prechat or postchat survey).

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfilled_form
propertiesnoobjectProperties
form_idyesstring
fieldsyesarrayThe fields a form contains. See form fields for details.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
form_idalways
fieldsalwaysAn array of form fields
Sample Filled form in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"form_id": "1473433500211",
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name",
			"answer": "Thomas Anderson"
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email",
			"answer": "t.anderson@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": {
				"id": "2",
				"group_id": 1,
				"label": "Marketing"
			}
		}
	]
}

Message

The Message event contains text message to other chat users.

Request

FieldRequiredData typeNotes
custom_idnostring
textyesstringMax. 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.
typeyesstringmessage
propertiesnoobjectProperties
postbacknoobjectIndicates that the message event was generated in response to a rich message event.
postback.idyesstringID of the postback from the rich message event.
postback.thread_idyesstringID of the thread with the rich message event.
postback.event_idyesstringID of the rich message event.
postback.typenostringShould be used together with postback.value (when one of them is present, the other is required).
postback.valuenostringShould be used together with postback.type (when one of them is present, the other is required).

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealwaysmessage
author_idalways
textalways
postbackoptionallyAppears in a message only when triggered by a rich message.
postback.idalways
postback.thread_idalways
postback.event_idalways
postback.typeoptionallyAppears only if postback.value is present.
postback.valueoptionallyAppears only if postback.type is present.
propertiesoptionallyProperties
Sample Rich message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"type": "message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"text": "hello there",
	"postback": {
		"id": "action_call",
		"thread_id": "K600PKZON8",
		"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
		"type": "phone",
		"value": "790034890"
	},
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

Rich message

Rich message event contains rich message data structure. Read more in a document dedicated to Rich messages.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
propertiesnoobjectThe properties data structure
template_idyesstringDefines how every Rich Message will be presented. Values: cards, sticker, or quick_replies.
elementsnoarrayCan contain up to 10 element objects.
elements.titleyesstringDisplays formatted text on RMs.
elements.subtitleyesstringDisplays formatted text on RMs.
elements.imageyesimageDisplays images on RMs. Required param: url; Optional params: name, content_type, size, width, height.
elements.buttonsnoarrayDisplays buttons. Can contain up to 13 button objects.
elements.buttons.textyesstringText displayed on a button.
elements.buttons.typeyesarrayDefines 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.valueyesstringShould be used together with elements.buttons.type.
elements.buttons.webview_heightyesstringRequired only for the webview buttontype. Possible values: compact, full, tall.
elements.buttons.postback_idyesstringA description of the sent action. Describes the action sent via send_rich_message_postback. More...
elements.buttons.user_idsyesarrayDescribes users that sent the postback with "toggled": true.

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string. Generated server-side.
propertiesoptionally
template_idalways
elementsoptionally
elements.titlealways
elements.subtitlealways
elements.imagealways
elements.buttonsoptionally
elements.buttons.textalways
elements.buttons.typealways
elements.buttons.valuealways
elements.buttons.webview_heightalwaysUnless button type is different than webview.
elements.buttons.postback_idalways
elements.buttons.user_idsalways
Sample Rich message in response
Copied!
{
	"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": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"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

Custom event is an event with customizable payload.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
propertiesnoobjectThe properties data structure

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
contentoptionally
propertiesoptionally
Sample Custom event in response
Copied!
{
	"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": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

System message

System message event is a native system event sent in specific situations.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give the system message a custom ID.
typeyesstringsystem_message
textnostringText displayed to recipients
system_message_typeyesstringSystem message type
text_varsnoobjectVariables used in the text

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
textoptionally
system_message_typealways
Sample System message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"type": "system_message",
	"text": "hello there",
	"system_message_type": "routing.assigned",
	"text_vars": {
		"agent": "John Doe"
	}
}

Available system messages

Here's the list of all system messages you might come across:

agent_added
ContentGenerated when
%initiator% added %agent% to the chatAgent was added to chat via the add_user_to_chat request and is not the first Agent in that chat.
agent_removed
ContentGenerated when
%initiator% removed %agent% from the chatAgent was removed from chat via the remove_user_from_chat request.
archived_customer_disconnected
ContentGenerated when
%customer% left the chatChat ended after Customer left the website.
chat_transferred
ContentGenerated when
%initiator% transferred the chat to %targets%Chat was transferred via the transfer_chat request.
customer_added
ContentGenerated when
%initiator% added %customer% to the chatCustomer was added to chat via the add_user_to_chat request.
customer_banned
ContentGenerated when
Chat archived because customer was banned by %agent% for %duration% day(s)Chat ended becaus Customer was banned via the ban_customer request.
customer_removed
ContentGenerated when
%initiator% removed %customer% from the chatCustomer was removed from chat via the remove_user_from_chat request.
manual_archived_agent
ContentGenerated when
%agent% archived the chatAgent closed chat via the deactivate_chat request.
manual_archived_customer
ContentGenerated when
%customer% archived the chatCustomer closed chat via the deactivate_chat request.
rating.chat_commented
ContentGenerated when
%customer% left the following comment: %comment%Chat was commented by Customer.
rating.chat_rated
ContentGenerated when
%customer% rated the chat as %score%Chat was rated by Customer.
rating.chat_rating_canceled
ContentGenerated when
%customer% canceled the chat ratingChat rating was cancelled by Customer.
routing.archived_deleted
ContentGenerated when
The chat was closed because %agent% account had been deletedChat was archived after Agent was removed from the license. No other Agent could be selected, and queues were disabled.
routing.archived_disconnected
ContentGenerated when
The chat was closed because %agent% had lost internet connectionChat was archived after Agent unexpectedly lost connection. No other Agent could be selected, and queues were disabled.
routing.archived_inactive
ContentGenerated when
Chat archived due to %duration% minutes of inactivityNo new messages were posted for an extended amount of time.
routing.archived_offline
ContentGenerated when
Chat archived due to no available agentsNo Agent could be selected after chat was placed in the queue.
routing.archived_other
ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.
routing.archived_remotely_signed_out
ContentGenerated when
The chat was closed because %agent% had been remotely signed outChat was archived after an Agent was logged out. No other Agent could be selected and queues were disabled.
routing.archived_signed_out
ContentGenerated when
The chat was closed because %agent% had signed outChat was archived after Agent logged out. No other Agent could be selected, and queues were disabled.
routing.assigned_deleted
ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% account had been deletedChat was assigned to a new Agent after the previous one was removed from the license.
routing.assigned_disconnected
ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% had lost internet connectionChat was assigned to a new Agent after the previous one unexpectedly lost connection.
routing.assigned_inactive
ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutesChat was assigned to a new Agent after the previous one failed to response in a timely manner.
routing.assigned_other
ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.
routing.assigned_remotely_signed_out
ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% had been remotely signed outChat was assigned to a new Agent after the previous one was logged out.
routing.assigned_signed_out
ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% had signed outChat was assigned to a new Agent after the previous one logged out.
routing.unassigned_deleted
ContentGenerated when
Customer was queued because %agent% account has been deletedChat was queued after Agent was removed from the license.
routing.unassigned_disconnected
ContentGenerated when
Customer was queued because %agent% had lost internet connectionChat was queued after Agent unexpectedly lost connection.
routing.unassigned_other
ContentGenerated when
Chat is unassignedChat was queued after Agent was removed from chat for other reasons.
routing.unassigned_remotely_signed_out
ContentGenerated when
Customer was queued because %agent% had been remotely signed outChat was queued after Agent was logged out.
routing.unassigned_signed_out
ContentGenerated when
Customer was queued because %agent% had signed outChat was queued after Agent logged out.
system_archived
ContentGenerated when
Chat archivedLicense was moved to another lc_serv instance while there were still active chats.
transcript_requested
ContentGenerated when
%customer% requested the chat transcript to be sent to %email%Customer enables transcript.

Users

Users are another important data structure. Within this data structure type, we can distinguish:

Customer

Sample Customer data structure
Copied!
{
	"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"type": "customer",
	"name": "Thomas Anderson",
	"email": "t.anderson@example.com",
	"avatar": "https://example.com/avatar.png",
	"session_fields": [
		{
			"custom_key": "custom_value"
		},
		{
			"another_custom_key": "another_custom_value"
		}
	],
	"present": true,
	"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.
avataroptional
emailoptional
nameoptional
session_fieldsoptionalAn array of custom object-enclosed key:value pairs. Available for the session duration.

Agent

Sample Agent data structure
Copied!
{
	"id": "b5657aff34dd32e198160d54666df9d8",
	"type": "agent",
	"name": "Agent Smith",
	"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

Sample Access data structure
Copied!
{
	"access": {
		"group_ids": [
			1,
			2
		]
	}
}
FieldReq./Opt.Note
group_idsrequiredgroup 0 means that all agents can see it.

Chats

Sample Chat data structure
Copied!
{
	"id": "PJ0MRSHTDG",
	"threads": [
		{
			"id": "QA1B38GHGI",
			"created_at": "2020-05-07T07:11:28.288340Z",
			"active": false,
			"user_ids": [
				"bbb67d600796e9f277e360e842418833",
				"b7eff798-f8df-4364-8059-649c35c9ed0c"
			],
			"events": [
				{
					"id": "QA1B38GHGI_1",
					"created_at": "2020-05-14T07:22:40.269000Z",
					"type": "message",
					"properties": {
						"source": {
							"client_id": "0805e283233042b37f460ed8fbf22160"
						}
					},
					"text": "hello",
					"author_id": "bbb67d600796e9f277e360e842418833",
					"custom_id": "1589440960204.71699349177"
				},
				{
					"id": "QA1B38GHGI_3",
					"created_at": "2020-05-14T08:18:44.015000Z",
					"type": "system_message",
					"text": "The chat was closed because Agent Smith had lost internet connection",
					"system_message_type": "routing.archived_disconnected",
					"text_vars": {
						"agent": "Agent Smith"
					}
				}
			],
			"properites": {
				"property_namespace": {
					"property_name": "property_value"
				}
			},
			"access": {
				"group_ids": [
					0
				]
			},
			"previous_thread_id": "K600PKZOM8",
			"next_thread_id": "K600PKZOO8"
		}
	],
	"users": [
		{
			"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"type": "customer",
			"present": true
		},
		{
			"id": "bbb67d600796e9f277e360e842418833",
			"name": "Agent Smith",
			"events_seen_up_to": "2020-05-14T07:22:37.287496Z",
			"type": "agent",
			"present": false,
			"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png",
			"job_title": "Support Agent"
		}
	],
	"access": {
		"group_ids": [
			0
		]
	},
	"properites": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}
FieldReq./Opt.
propertiesoptional
accessoptional

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_event_per_type.

Sample Chat summary data structure
Copied!
{
	"id": "PJ0MRSHTDG",
	"last_thread_id": "QA1B38GHGI",
	"last_thread_created_at": "2020-05-08T08:22:21.128420Z",
	"users": [
		{
			"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"type": "customer",
			"present": true
		},
		{
			"id": "bbb67d600796e9f277e360e842418833",
			"name": "Agent Smith",
			"events_seen_up_to": "2020-05-14T07:22:37.287496Z",
			"type": "agent",
			"present": false,
			"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png",
			"job_title": "Support Agent"
		}
	],
	"last_event_per_type": {
		"message": {
			"thread_id": "QA1B38GHGI",
			"thread_order": 1,
			"thread_created_at": "2020-05-14T07:22:30.779000Z",
			"event": {
				"id": "QA1B38GHGI_1",
				"created_at": "2020-05-14T07:22:40.269000Z",
				"type": "message",
				"properties": {
					"property_namespace": {
						"property_name": "property_value"
					}
				},
				"text": "Hello",
				"author_id": "bbb67d600796e9f277e360e842418833",
				"custom_id": "1589440960204.71699349177"
			}
		},
		"system_message": {
			"thread_id": "QA1B38GHGI",
			"thread_order": 1,
			"thread_created_at": "2020-05-14T07:22:30.779000Z",
			"event": {
				"id": "QA1B38GHGI_3",
				"created_at": "2020-05-14T08:18:44.015000Z",
				"type": "system_message",
				"text": "The chat was closed because Agent Smith had lost internet connection",
				"system_message_type": "routing.archived_disconnected",
				"text_vars": {
					"agent": "Agent Smith"
				}
			}
		}
	},
	"properites": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"access": {
		"group_ids": [
			0
		]
	},
	"active": false
}

Form fields

A component of the Filled form event.

Sample Form fields
Copied!
{
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name",
			"answer": "Thomas Anderson"
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email",
			"answer": "t.anderson@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": {
				"id": "2",
				"group_id": 1,
				"label": "Marketing"
			}
		}
	]
}
FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types
answeryesanyFor all field types
answer.idyesstringAn identifier of each option a Customer can choose. For all field types.
answer.labelyesstringAnswer label; for all field types
answer.group_idyesnumberFor group_chooser

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.

Sample Properties data structure
Copied!
{
	"properties": {
		"0805e283233042b37f460ed8fbf22160": {
			"string_property": "string value"
		}
	}
}

Threads

Sample Thread data structure
Copied!
{
	"id": "K600PKZON8",
	"active": true,
	"user_ids": [
		"b7eff798-f8df-4364-8059-649c35c9ed0c"
	],
	"restricted_access": true,
	"events": [
		{
			"id": "QA1B38GHGI_1",
			"created_at": "2020-05-14T07:22:40.269000Z",
			"type": "message",
			"properties": {
				"property_namespace": {
					"property_name": "property_value"
				}
			},
			"text": "hello",
			"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"custom_id": "1589440960204.71699349177"
		}
	],
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"access": {
		"group_ids": [
			0
		]
	},
	"queue": {
		"position": 42,
		"wait_time": 1337,
		"queued_at": "2020-05-07T07:11:28.288340Z"
	},
	"previous_thread_id": "K600PKZOM8",
	"next_thread_id": "K600PKZOO8",
	"created_at": "2020-05-07T07:11:28.288340Z"
}
FieldReq./Opt.Note
accessoptional
activerequiredPossible values: true (thread is still active) or false(thread no longer active).
eventsoptionalDoesn't exists if restricted_access is true.
propertiesoptional
restricted_accessoptional
queueoptionalPresent only if the chat is in the queue. Wait time is approximated in seconds.
previous_thread_idoptionalPresent only if there is a preceding thread.
next_thread_idoptionalPresent only if there is a following thread.
created_atrequiredDate & time format with a resolution of microseconds, UTC string. Generated server-side.

Methods

The API endpoint

wss://api.livechatinc.com/v3.2/customer/rtm/ws

When connecting to the Customer Chat RTM API, clients have to send over the required query string parameters.

Required parameterData typeNotes
license_idintegerLiveChat account ID
GENERAL RTM API REQUEST FORMAT
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "payload": {
  // optional
  }
}
GENERAL RTM API RESPONSE FORMAT
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "type": "response",
  "success": true,
  "payload": {
  // optional
  }
}

Chats

List Chats

It returns summaries of the chats a Customer participated in.

Specifics
Actionlist_chats
Web API equivalentlist_chats
Push message-
Request
ParameterRequiredTypeNotes
limitNonumberDefault: 10, maximum: 25
sort_orderNostringPossible values: asc, desc (default). Chat summaries are sorted by the creation date of its last thread.
page_idNostring
Response
ParameterData typeNotes
total_chatsnumberAn estimated number. The real number of found chats can slightly differ.
next_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's the next page.
previous_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's the previous page.
chats_summaryarrayArray of Chat summary data structures.
REQUEST
Copied!
{
  "action": "list_chats",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "list_chats",
  "type": "response",
  "success": true,
  "payload": {
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "chats_summary": [{
      "id": "PJ0MRSHTDG",
      "last_thread_id": "K600PKZON8",
      "last_thread_created_at": "2020-05-08T08:22:21.128420Z",
      "last_event_per_type": {
        "message": {
          "thread_id": "K600PKZON9",
          "thread_created_at": "2020-05-07T07:11:28.288340Z",
          "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": "b5657aff34dd32e198160d54666df9d8",
        "name": "Agent Smith",
        "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
  }
}

List Threads

It returns threads that the current Customer has access to in a given chat.

Specifics
Actionlist_threads
Web API equivalentlist_threads
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstring
sort_orderNostringPossible values: asc - oldest threads first and desc - newest threads first (default).
limitNonumberDefault: 3, maximum: 100
page_idNostring
min_events_countNonumberRange: 1-100; Specifies the minimum number of events to be returned in the response. It's the total number of events, so they can come from more than one thread. You'll get as many latest threads as needed to meet the min_events_count condition.

You cannot use both limit and min_events_count at the same time.

REQUEST
Copied!
{
  "action": "list_threads",
    "payload": {
      "chat_id": "PWJ8Y4THAV"
    }
}
Response
Copied!
{
  "request_id": "<request_id>",
  "action": "get_chat",
  "type": "response",
  "success": true,
  "payload": {
    "threads": [{
      "id": "K600PKZON8",
      "created_at": "2019-12-17T07:57:41.512000Z",
      "active": true,
      "user_ids": [
        "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "bbb67d600796e9f277e360e842418833"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "recipients": "all",
        "type": "message",
        "text": "Hello",
        "author_id": "bbb67d600796e9f277e360e842418833"
      }],
      "properties": {
        // "Property" object
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8", // optional
      "next_thread_id": "K600PKZOO8" // optional
    }],
    "found_threads": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
    "previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
  }
}

Get Chat

Specifics
Actionget_chat
Web API equivalentget_chat
Push message-
Request
ParameterRequiredData type
chat_idYesstring
thread_idNostringDefault: the latest thread (if exists)
REQUEST
Copied!
{
  "action": "get_chat",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8"
  }
}
Response
Copied!
{
  "request_id": "<request_id>",
  "action": "get_chat",
  "type": "response",
  "success": true,
  "payload": {
    "id": "PJ0MRSHTDG",
    "thread": {
      "id": "K600PKZON8",
      "created_at": "2020-05-07T07:11:28.288340Z",
      "active": true,
      "user_ids": [
        "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "b5657aff34dd32e198160d54666df9d8"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "type": "message",
        "text": "Hello",
        "author_id": "b5657aff34dd32e198160d54666df9d8"
      }],
      "properties": {
        "0805e283233042b37f460ed8fbf22160": {
          "string_property": "string_value"
        }
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8",
      "next_thread_id": "K600PKZOO8"
    },
    "users": [{
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "type": "customer",
      "present": true
    }, {
      "id": "b5657aff34dd32e198160d54666df9d8",
      "name": "Agent Smith",
      "type": "agent",
      "present": true,
      "avatar": "https://example.com/avatar.jpg",
      "job_title": "Support Agent"
    }],
    "access": {
      "group_ids": [0]
    },
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string_value"
      }
    }
  }
}

Start Chat

Starts a chat.

Specifics
Actionstart_chat
Web API equivalentstart_chat
Push messageincoming_chat
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobjectInitial chat properties
chat.accessNoobjectChat access to set, default: all agents.
chat.usersNoarrayList of existing users. Only one user is allowed (type customer).
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial thread properties
continuousNoboolStarts chat as continuous (online group is not required); default: false.
Response
ParameterData typeNotes
chat_idstring
thread_idstring
event_ids[]stringReturned 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
Copied!
{
  "action": "start_chat",
  "payload": {}
}
Response
Copied!
{
  "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
Actionactivate_chat
Web API equivalentactivate_chat
Push messageincoming_chat
Request
Request objectRequiredTypeNotes
chatYesobject
chat.idYesstringThe ID of the chat that will be activated.
chat.accessNoobjectChat access to set, default: all agents.
chat.propertiesNoobjectInitial chat properties
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial thread properties
continuousNoboolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Response
ParameterData typeNotes
thread_idstring
event_ids[]stringReturned 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
Copied!
{
  "action": "activate_chat",
  "payload": {
  "chat": {
    "id": "PWJ8Y4THAV"
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "activate_chat",
  "type": "response",
  "success": true,
  "payload": {
  "thread_id": "Z8AGR5OUW"
  }
}

Deactivate Chat

Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible.

Specifics
Actiondeactivate_chat
Web API equivalentdeactivate_chat
Push messageincoming_event and chat_deactivated
Request
ParameterRequiredData type
chat_idYesstring
REQUEST
Copied!
{
  "action": "deactivate_chat",
  "payload": {
  "chat_id": "PJ0MRSHTDG"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "deactivate_chat",
  "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
Actionsend_event
Web API equivalentsend_event
Push messageincoming_event
Request
ParametersRequiredData typeNotes
chat_idYesstringId of the chat you want to send the message to.
eventYesobjectThe Event object
attach_to_last_threadNoboolIf true, adds an event to the last (inactive) thread. Otherwise, it doesn't create a new one, default: false.
REQUEST
Copied!
{
  "action": "send_event",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "event": {
    "type": "message",
    "text": "hello world",
    "recipients": "all"
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_event",
  "type": "response",
  "success": true,
  "payload": {
   "event_id": "K600PKZON8"
  }
}

Send Rich Message Postback

Specifics
Actionsend_rich_message_postback
Web API equivalentsend_rich_message_postback
Push messageincoming_rich_message_postback*

*) incoming_rich_message_postback will be sent only for active threads.

Request
ParameterRequiredData typeNotes
chat_idYesstring
event_idYesstring
postbackYesobject
postback.idYesstringPostback name of the button
postback.toggledYesboolPostback toggled, true or false
thread_idYesstring
REQUEST
Copied!
{
  "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
  }
  }
}
Response
Copied!
{
  "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
Actionsend_sneak_peek
Web API equivalentsend_sneak_peek
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat to send a sneak peek to.
sneak_peek_textYesstringSneak peek text
REQUEST
Copied!
{
  "action": "send_sneak_peek",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "sneak_peek_text": "hello world"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_sneak_peek",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Properties

Update Chat Properties

Specifics
Actionupdate_chat_properties
Web API equivalentupdate_chat_properties
Push messagechat_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you to set a property for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_chat_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat property value updated by Customer"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_chat_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Delete Chat Properties

Specifics
Actiondelete_chat_properties
Web API equivalentdelete_chat_properties
Push messagechat_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
propertiesYesobjectChat properties to delete.
REQUEST
Copied!
{
  "action": "delete_chat_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_chat_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Update Thread Properties

Specifics
Actionupdate_thread_properties
Web API equivalentupdate_thread_properties
Push messagethread_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_thread_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
    "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Thread property value updated by Customer"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_thread_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Delete Thread Properties

Specifics
Actiondelete_thread_properties
Web API equivalentdelete_thread_properties
Push messagethread_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
propertiesYesobjectThread properties to delete.
REQUEST
Copied!
{
  "action": "delete_thread_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_thread_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Update Event Properties

Specifics
Actionupdate_event_properties
Web API equivalentupdate_event_properties
Push messageevent_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
event_idYesstringId of the event you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_event_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Event property value updated by Customer"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_event_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Delete Event Properties

Specifics
Actiondelete_event_properties
Web API equivalentdelete_event_properties
Push messageevent_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
event_idYesstringId of the event you want to delete the properties of.
propertiesYesobjectEvent properties to delete.
REQUEST
Copied!
{
  "action": "delete_event_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_event_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Customers

Update Customer

Specifics
Actionupdate_customer
Web API equivalentupdate_customer
Push messagecustomer_updated
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar.
session_fieldsNo[]objectAn array of custom object-enclosed key:value pairs. Respects the order of items.

At least one optional parameter needs to be included in the request payload.

REQUEST
Copied!
{
  "action": "update_customer",
  "payload": {
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "example.com/avatars/1.png",
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }]
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_customer",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Update Customer Page

Specifics
Actionupdate_customer_page
Web API equivalent-
Push messagecustomer_page_updated

Agent and referrer are updated by default using the browser’s headers.

Request
ParameterRequiredData type
urlYesstring
titleNostring
REQUEST
Copied!
{
  "action": "update_customer_page",
  "payload": {
  "url": "https://livechatinc.com/pricing"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_customer_page",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Set Customer Session Fields

Specifics
Actionset_customer_session_fields
Web API equivalentset_customer_session_fields
Push messagecustomer_updated
Request
ParameterRequiredData typeNotes
session_fieldsYes[]objectAn array of custom object-enclosed key:value pairs. Respects the order of items. Max keys: 100

Agent and referrer are updated by default using the browser’s headers.

REQUEST
Copied!
{
  "action": "set_customer_session_fields",
  "payload": {
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }],
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "set_customer_session_fields",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Get Customer

Returns the info about the Customer requesting it.

Specifics
Actionget_customer
Web API equivalentget_customer
Push message-
Response
nameCustomer's name. Returned only if set.
emailCustomer's email. Returned only if set.
avatarCustomer's avatar. Returned only if set.
session_fieldsAn array of custom object-enclosed key:value pairs. Returned only if set. Available for the session duration.
REQUEST
Copied!
{
  "action": "get_customer",
  "payload": {
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }],
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_customer",
  "type": "response",
  "success": true,
  "payload": {
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "Thomas Anderson", // optional
  "email": "t.anderson@example.com", // optional
  "avatar": "https://example.com/avatars/1.jpg", // optional
  "session_fields": [{ // optional
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }]
  }
}

Status

Login

It returns the initial state of the current Customer.

Specifics
Actionlogin
Web API equivalent-
Push message-
Request
ParameterRequiredData typeNotes
tokenYesstringOAuth token from the Customer's account
customerNoobject
customer.avatarNostringThe URL of the Customer's avatar
customer.emailNostring
customer.nameNostring
customer.session_fieldsNo[]objectAn array of custom object-enclosed key:value pairs. Respects the order of items.
customer_page.titleNostring
customer_page.urlNostring
customer_side_storage*NoobjectA map in the "key": "value" format
is_mobileNoboolInforms if logging in is performed from a mobile device.
group_idNonumber
referrerNostring
applicationNoobjectApplication info
application.nameNostringApplication name
application.versionNostringApplication version
application.channel_typeNostringApplication channel type

*) 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
Copied!
{
  "action": "login",
  "payload": {
    "token": "Bearer dal:test_1fgTbfXmgthj4cZSA"
    }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "login",
  "type": "response",
  "success": true,
  "payload": {
    "customer": {
      "id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
      "name": "Thomas Anderson",
      "email": "t.anderson@example.com",
      "avatar": "https://example.com/avatar.png",
      "session_fields": [{
        "custom_key": "custom_value"
      }, {
        "another_custom_key": "another_custom_value"
      }],
      "statistics": {
        "chats_count": 2,
        "threads_count": 9,
        "visits_count": 15,
        "page_views_count": 40,
        "greetings_shown_count": 20,
        "greetings_accepted_count": 1
      }
    },
    "has_active_thread": true,
    "chats": [{
      "chat_id": "PJ0MRSHTDG",
      "has_unread_events": true
    }],
    "greeting": {
      "accepted": true, // Customer has seen the greeting
      "id": 342543723,
      "unique_id": "e35a4fb4106d87e550fe1af480639058",
      "addon": "email",
      "event": {
        // "Event > Message" object
        // or
        // "Event > Rich message" object
      },
      "agent": {
        "id": "b5657aff34dd32e198160d54666df9d8",
        "name": "Agent Smith",
        "type": "agent",
        "avatar": "https://example.com/avatar.png",
        "job_title": "Support Agent",
        "is_bot": false
      },
      "displayed_first_time": true
    },
    "__priv_dynamic_config": {
      "online_groups_ids": [1, 3],
      "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"
        }
      }
    }
  }
}

List Group Statuses

Specifics
Actionlist_group_statuses
Web API equivalentlist_group_statuses
Push message-
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, you will get statuses of all the groups.
group_idsNoarrayA table of a groups' IDs

One of the optional parameters needs to be included in the request payload.

Response
Group Not FoundIf you send group_id of a group that doesn't exists, the id won't be included in the resposne payload.
REQUEST
Copied!
{
  "action": "list_group_statuses",
  "payload": {
  "all": true
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "list_group_statuses",
  "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
Actionget_form
Web API equivalentget_form
Push message-
Request
ParameterRequiredData typeNotes
group_idYesnumberId of the group from which you want the form.
typeYesstringForm type. Possible values: prechat or postchat.
Response
ParameterNotes
enabledIf enabled: false, the form object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI.
headerFor headers; the field has no answer, therefore is not sent in the Filled form event.
ratingFor rating; the field has no answer, therefore is not sent in the Filled form event.
REQUEST
Copied!
{
  "action": "get_form",
  "payload": {
  "group_id": 0,
  "type": "prechat"
  }
}
Response
Copied!
{
  "form": {
    "id": "157986144052005549",
    "fields": [
      {
        "id": "157986144052003238",
        "type": "header",
        "label": "Welcome to our LiveChat! Please fill in the form below before starting the chat."
      },
      {
        "id": "157986144052008371",
        "type": "name",
        "label": "Name:",
        "required": false
      },
      {
        "id": "157986144052005782",
        "type": "email",
        "label": "E-mail:",
        "required": false
      },
      {
        "id": "157986144052009331",
        "type": "group_chooser",
        "label": "Choose a department:",
        "required": true,
        "options": [
          {
            "id": "0",
            "group_id": 1,
            "label": "Marketing"
          },
          {
            "id": "1",
            "group_id": 2,
            "label": "Sales"
          },
          {
            "id": "2",
            "group_id": 0,
            "label": "General"
          }
        ]
      }
    ]
  },
  "enabled": true
}

Get Predicted Agent

Gets the predicted Agent - the one the Customer will chat with when the chat starts.

Specifics
Actionget_predicted_agent
Web API equivalentget_predicted_agent
Push message-
REQUEST
Copied!
{
  "action": "get_predicted_agent",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_predicted_agent",
  "type": "response",
  "success": true,
  "payload": {
  "id": "b5657aff34dd32e198160d54666df9d8",
  "name": "Agent Smith",
  "avatar": "https://example.avatar/example.com",
  "is_bot": false,
  "job_title": "support hero",
  "type": "agent"
  }
}

Get URL Info

It returns the info on a given URL.

Specifics
Actionget_url_info
Web API equivalentget_url_info
Push message-
Request
ParameterRequiredData typeNotes
urlYesstringValid website URL
Response
ParameterData typeNotes
image_urlstringURL of the minified image hosted on the LiveChat's CDN
image_original_urlstringURL of the original image
REQUEST
Copied!
{
  "action": "get_url_info",
  "payload": {
  "url": "https://livechatinc.com"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_url_info",
  "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": "https://example.com/image.png",
  "image_original_url": "https://example-original-url.com/image.png",
  "image_width": 200,
  "image_height": 200,
  "url": "https://livechatinc.com"
  }
}

Mark Events As Seen

Specifics
Actionmark_events_as_seen
Web API equivalentmark_events_as_seen
Push messageevents_marked_as_seen
Request
ParameterRequiredData typeNotes
chat_idYesstring
seen_up_toYesstringRFC 3339 date-time format
Response

No response payload (200 OK).

REQUEST
Copied!
{
  "action": "mark_events_as_seen",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "seen_up_to": "2017-10-12T15:19:21.010200Z"
  }
}

Accept Greeting

Marks an incoming greeting as seen.

How it's implemented in LiveChat:

The Chat Widget uses this method to inform that a Customer has seen a greeting. Based on that, the Reports section displays the greetings that were actually seen by Customers, not all the sent greetings. If a Customer started a chat from a greeting, but the Accept Method wasn't executed, the greeting is still counted as seen in Reports.

Specifics
Actionaccept_greeting
Web API equivalentaccept_greeting
Push messagegreeting_accepted
Request
ParameterRequiredData typeNotes
greeting_idYesnumberID of the greeting configured within the license to accept.
unique_idYesstringID of the greeting to accept. You can get it from the incoming_greeting push.
REQUEST
Copied!
{
  "action": "accept_greeting",
  "payload": {
    "greeting_id": 7,
    "unique_id": "Q10X0W041P"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "accept_greeting",
  "type": "response",
  "payload": {
    // no response payload
  },
  "success": true
}

Cancel Greeting

Cancels a greeting (an invitation to the chat). For example, Customers could cancel greetings by minimizing the chat widget with a greeting.

Specifics
Actioncancel_greeting
Web API equivalentcancel_greeting
Push messagegreeting_canceled
Request
ParameterRequiredData typeNotes
unique_idYesstringID of the greeting to cancel. You can get it from the incoming_greeting push.
REQUEST
Copied!
{
  "action": "cancel_greeting",
  "payload": {
    "unique_id": "Q10X0W041P"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "cancel_greeting",
  "type": "response",
  "payload": {
  // no response payload
  },
  "success": true
}

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.
The general push format
Copied!
{
  "request_id": "<request_id>", // optional, applies only to the requester
  "action": "<action>",
  "type": "push",
  "payload": {
  // optional payload
  }
}

Chats

incoming_chat

Informs about a chat coming with a new thread. The push payload contains the whole chat data structure. If the chat was started with some initial events, the thread object contains them.

Sample push payload
Copied!
{
  "requester_id": "b5657aff34dd32e198160d54666df9d8",
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [
      // array of "User" objects
    ],
    "properties": {
      // "Properties" object
    },
    "access": {
      // "Access" object
    },
    "thread": {
      // "Thread" object
    },
    "transferred_from": {
      "group_ids": [ 1 ],
      "agent_ids": [ "bbb67d600796e9f277e360e842418833" ]
    }
  }
}
Specifics
Actionincoming_chat
Webhook equivalentincoming_chat

chat_deactivated

Informs that a chat was deactivated by closing the currently open thread.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
}
Specifics
Actionchat_deactivated
Webhook equivalentchat_deactivated
Push payload
ObjectNotes
user_idMissing if a thread was closed by the router.

Chat access

chat_transferred

Informs that a chat was transferred to a different group or to an Agent.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "requester_id": "b5657aff34dd32e198160d54666df9d8",
  "transferred_to": {
    "group_ids": [ 1 ],
    "agent_ids": ["b5657aff34dd32e198160d54666df9d8"],
  },
  "queue": {
    "position": 42,
    "wait_time": 1337,
    "queued_at": "2019-12-09T12:01:18.909000Z"
  }
}
Specifics
Actionchat_transferred
Webhook equivalent-
Push payload
ObjectNotes
thread_idPresent if the chat is active
transferred_toIDs of groups and Agents the chat has been assigned to
queuePresent if the chat is queued after the transfer

Chat users

user_added_to_chat

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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user": {
  // "User > Customer" or "User > Agent" object
  },
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}
Specifics
Actionuser_added_to_chat
Webhook equivalentuser_added_to_chat
Push payload
ObjectNotes
thread_idPresent when a user was added to an active chat.
reasonWhy the user was added.
requester_idPresent if the user was added by an agent.

user_removed_from_chat

Informs that a user (Customer or Agent) was removed from a chat.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "bbb67d600796e9f277e360e842418833",
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}
Specifics
Actionuser_removed_from_chat
Webhook equivalentuser_removed_from_chat
Push payload
ObjectNotes
thread_idPresent when a user was removed from an active chat.
reasonWhy the user was removed.
requester_idPresent if the user was removed by an agent.

Events

incoming_event

Informs about an incoming event sent to a chat.

Sample push payload
Copied!
{
  "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": "string value"
      }
    },
    "text": "Hello",
    "author_id": "b5657aff-34dd-32e1-98160d54666df9d8"
  }
}
Specifics
Actionincoming_event
Webhook equivalentincoming_event

event_updated

Informs that an event was updated.

Sample push payload
Copied!
{
  "chat_id": "123-123-123-123",
  "thread_id": "E2WDHA8A",
  "event": {
  // "Event" object
  }
}
Specifics
Actionevent_updated
Webhook equivalentevent_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.

Sample push payload
Copied!
{
  "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
Actionincoming_rich_message_postback
Webhook equivalentincoming_rich_message_postback

Properties

chat_properties_updated

Informs about those chat properties that were updated.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Chat property value updated by Customer"
    },
  // ...
  }
}
Specifics
Actionchat_properties_updated
Webhook equivalentchat_properties_updated
Push payload
ObjectNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Specifics
Actionchat_properties_deleted
Webhook equivalentchat_properties_deleted
Push payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.

thread_properties_updated

Informs about those thread properties that were updated.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Thread property value updated by Customer"
    },
  // ...
  }
}
Specifics
Actionthread_properties_updated
Webhook equivalentthread_properties_updated
Push payload
ObjectNotes
propertiesThis is not a full properties object. This push shows only the properties the have been recently updated.

thread_properties_deleted

Informs about those thread properties that were deleted.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Specifics
Actionthread_properties_deleted
Webhook equivalentthread_properties_deleted
Push payload
ObjectNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Event property value updated by Customer"
    }
  }
}
Specifics
Actionevent_properties_updated
Webhook equivalentevent_properties_updated
Push payload
ObjectNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Specifics
Actionevent_properties_deleted
Webhook equivalentevent_properties_deleted
Push payload
ObjectNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "customer": {
  // "User > Customer" object
  }
}
Specifics
Actioncustomer_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.

Sample push payload
Copied!
{
  "url": "https://livechatinc.com/pricing",
  "title": "pricing",
  "timestamp": 123456789
}
Specifics
Actioncustomer_page_updated
Webhook equivalent-

customer_side_storage_updated

Informs that a Customer updated the data stored on their side.

Sample push payload
Copied!
{
  "customer_side_storage": {
  "customer_visits": "1"
  }
}
Specifics
Actioncustomer_side_storage_updated
Webhook equivalent-
Push payload
ObjectNotes
customer_side_storageA 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.

Sample push payload
Copied!
{
  "reason": "misdirected_connection",
  "data": {
  // optional
  "region": "fra"
  }
}
Specifics
Actioncustomer_disconnected
Webhook equivalent-
Push payload
ObjectNotes
reason
Possible reasons
TypeNotes
access_token_expiredAccess token lifetime has elapsed.
connection_timeoutHas not received ping from the client for some time, or it's been too long since the connection was authorized.
customer_bannedCustomer has been banned.
customer_temporarily_blocked*Customer tried reconnecting too many times after the too_many_connections error had occurred.
inactivity_timeoutCustomer didn't chat or change the page in the past 30 minutes.
internalInternal error
license_not_foundThe license with the specified ID doesn't exist.
misdirected_connection **Customer connected to a server in the wrong region.
product_version_changedThe product version has changed.
too_many_connectionsCustomer has reached the maximum number of connections.
too_many_unauthorized_connectionsThe maximum number of unauthorized connections has been reached.
unsupported_versionConnecting to an unsupported version of the Customer Chat API.

*) 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.

**) 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.

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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "typing_indicator": {
  "author_id": "d17cd570-11a9-45c0-45c0-1b020b7586dc",
  "recipients": "all",
  "timestamp": 1574245378,
  "is_typing": true
  }
}
Specifics
Actionincoming_typing_indicator
Webhook equivalent-

incoming_multicast

Informs about messages sent via the multicast method or by the system.

Sample push payload
Copied!
{
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "content": {
  "example": {
    "nested": "json"
  }
  }
}
Specifics
Actionincoming_multicast
Webhook equivalent-
Push payload
ObjectRequiredNotes
author_idNoPresent only if the push was generated by the Multicast method and not sent from the server.
contentYes

events_marked_as_seen

Informs that a user has seen events up to a specific time.

Sample push payload
Copied!
{
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "chat_id": "PJ0MRSHTDG",
  "seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Specifics
Actionevents_marked_as_seen
Webhook equivalentevents_marked_as_seen

incoming_greeting

Informs about an incoming greeting.

Sample push payload
Copied!
{
  "action": "incoming_greeting",
  "type": "push",
  "payload": {
  "id": 7,
  "unique_id": "Q10O0N5B5D",
  "displayed_first_time": true,
  "addon": "email",
  "event": {
    // "Event > Message" object
    // or
    // "Event > Rich message" object
  },
  "agent": {
    "name": "Agent Smith",
    "id": "b5657aff34dd32e198160d54666df9d8",
    "avatar": "https://example.com/image25.png",
    "job_title": "Support Agent",
    "is_bot": false
  }
  }
}
Specifics
Actionincoming_greeting
Webhook equivalent-
Push payload
ObjectNotes
idID of the greeting configured within the license.
unique_idID of the greeting that was generated, sent, and cancelled.
eventGreeting event (Message or Rich message)
displayed_first_timetrue if the greeting was generated for the first time.
agentInfo about the Agent who sent the greeting.
addonAdditional greeting property

greeting_accepted

Informs about a greeting accepted by the Customer.

Sample push payload
Copied!
{
  "action": "greeting_accepted",
  "type": "push",
  "payload": {
  "unique_id": "Q40R0832IN"
  }
}
Specifics
Actiongreeting_accepted
Webhook equivalent-
Push payload
ObjectNotes
unique_idID of the greeting that was generated, sent, and accepted.

greeting_canceled

Informs about a greeting rejected by the Customer. Also, the push is sent when a new greeting automatically cancels the currently displayed one.

Sample push payload
Copied!
{
  "action": "greeting_canceled",
  "type": "push",
  "payload": {
    "unique_id": "Q10O0N5B5D"
  }
}
Specifics
Actiongreeting_canceled
Webhook equivalent-
Push payload
ObjectNotes
unique_idID of the greeting that was generated, sent, and rejected.

queue_position_updated

Informs about an updated position in the queue and about the wait time.

Sample push payload
Copied!
{
  "action": "queue_position_updated",
  "type": "push",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "queue": {
      "position": 42,
      "wait_time": 1337
    }
  }
}
Specifics
Actionqueue_position_updated
Webhook equivalent-

Errors

General error format
Copied!
{
  "error": {
  "type": "misdirected_request",
  "message": "Wrong region",
  "data": {
    // optional
    "region": "dal"
  }
  }
}
Possible errors
TypeDefault MessageNotes
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorUser is not allowed to perform the action.
customer_bannedCustomer is bannedThe customer had been banned.
greeting_not_foundGreeting not found
group_not_foundGroup not found
group_offlineGroup is offlineThrown in response to Get Predicted Agent.
group_unavailableNo agent available for groupThrown in response to Get Predicted Agent. The group is online, but there are no available Agents.
groups_offlineGroups offline
internalInternal server error
license_expiredLicense expiredThe end of license trial or subcription.
pending_requests_limit_reachedRequests limit reachedThe limit of pending requests within one websocket connection has been reached. The limit is 10.
request_timeoutRequest timed outTimeout threshold is 15 seconds.
users_limit_reachedUsers limit reachedDisplayed on the attempt of logging in. The limit of online Customers for a given license has been reached.
unsupported_versionUnsupported versionUnsupported protocol version.
validationWrong format of request
wrong_product_versionWrong product versionLicense 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@livechatinc.com. We'll be happy to hear from you!