API version

RTM API Reference

10 minutes reading time

Introduction

Versioning

This documentation describes the Agent 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 - Agent 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.

Agent 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 Agent Chat Web API instead.

Access

The basics on authorization, server pinging, and scopes in the Agent Chat RTM API.

Authorization

Agent authorization is handled with access tokens. Find out how to get an access token from Agent authorization flows. 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.

Scopes

All authorization scopes are listed in the Scopes document. If a method requires particular authorization scopes, you'll find them included in the method description.

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 Agent 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/agent/rtm/ws

dal: wss://api.livechatinc.com/v3.2/agent/rtm/ws

Rate limits

To prevent sending a massive number of requests, there are rate limits for method calls. After exceeding those limits, the requester will get a Too many requests error in the response of a specific request. After some time, the request will be unblocked so it can be sent again.

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 data structures.

These are the available event types:

File

The File event informs about an uploaded file.

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfile
recipientsyesstringPossible values: all (default), agents
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
recipientsalways
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",
	"type": "file",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"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
recipientsyesstringPossible values: all (default), agents
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
recipientsalways
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",
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"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
recipientsyesstringPossible values: all (default), agents
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
recipientsalways
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 Message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"text": "hello there",
	"postback": {
		"id": "action_call",
		"thread_id": "K600PKZON8",
		"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
		"type": "phone",
		"value": "790034890"
	},
	"recipients": "all",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

Rich message

Rich message (RM) event contains a rich message data structure. Read more about rich messages.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
recipientsyesstringThose who can display the rich message: all (default) or agents
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 (when one of them is present, the other is required). Possible values: webview, message, url, phone. More...
elements.buttons.valueyesstringShould be used together with elements.buttons.type (when one of them is present, the other is required).
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.
recipientsalways
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",
	"recipients": "all",
	"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
recipientsyesstringThose who can receive the custom event: all (default) or agents
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
recipientsalways
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"
		}
	},
	"recipients": "all",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

System message

System message event is 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
recipientsnostringIt can be specified when sending system messages via the Send Event method. Possible values: all, agents.
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
recipientsoptionally
Sample System message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "system_message",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"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:

Agent

Sample Agent data structure
Copied!
{
	"id": "smith@example.com",
	"type": "agent",
	"name": "Agent Smith",
	"email": "smith@example.com",
	"present": true,
	"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
	"avatar": "cdn.livechatinc.com/avatars/1.png",
	"routing_status": "accepting_chats"
}
FieldReq./Opt.Note
routing_statusoptionalReturned only if the Agent's currently logged in.
events_seen_up_tooptionalRFC 3339 datetime string; the timestamp of the most recent event seen by the Agent—all the previous events are considered seen.

My profile

Sample My profile data structure
Copied!
{
	"id": "smith@example.com",
	"type": "agent",
	"name": "Agent Smith",
	"email": "smith@example.com",
	"present": true,
	"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
	"avatar": "cdn.livechatinc.com/avatars/1.png",
	"routing_status": "accepting_chats",
	"permission": "administrator"
}
FieldReq./Opt.Notes
events_seen_up_tooptionalRFC 3339 datetime string; the timestamp of the most recent event seen by the Agent—all the previous events are considered seen.

Customer

Sample Customer data structure
Copied!
{
	"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"type": "customer",
	"name": "Thomas Anderson",
	"email": "t.anderson@example.com",
	"avatar": "example.com/avatars/1.png",
	"last_visit": {
		"started_at": "2017-10-12T15:19:21.010200Z",
		"referrer": "http://www.google.com/",
		"ip": "<customer_ip>",
		"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
		"geolocation": {
			"country": "Poland",
			"country_code": "PL",
			"region": "Dolnoslaskie",
			"city": "Wroclaw",
			"timezone": "Europe/Warsaw"
		},
		"last_pages": [
			{
				"opened_at": "2017-10-12T15:19:21.010200Z",
				"url": "https://www.livechatinc.com/",
				"title": "LiveChat - Homepage"
			},
			{
				"opened_at": "2017-10-12T15:19:21.010200Z",
				"url": "https://www.livechatinc.com/tour",
				"title": "LiveChat - Tour"
			}
		]
	},
	"session_fields": [
		{
			"custom_key": "custom_value"
		},
		{
			"another_custom_key": "another_custom_value"
		}
	],
	"statistics": {
		"chats_count": 3,
		"threads_count": 9,
		"visits_count": 5
	},
	"__priv_lc2_customer_id": "test_771305.dafea66e5c",
	"agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
	"customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
	"created_at": "2017-10-11T15:19:21.010200Z",
	"present": true,
	"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.Notes
agent_last_event_created_atoptional
avataroptional
customer_last_event_created_atoptional
created_atoptional
emailoptional
session_fieldsoptionalAn array of custom object-enclosed key:value pairs. Expires along with the session.
nameoptional
events_seen_up_tooptionalRFC 3339 datetime string
last_visitoptional
presentoptional
statisticsoptional

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": "QA37PVJ75B",
			"created_at": "2020-05-12T11:42:47.383000Z",
			"active": false,
			"user_ids": [
				"smith@example.com",
				"b7eff798-f8df-4364-8059-649c35c9ed0c"
			],
			"events": [
				{
					"id": "QA37PVJ75B_1",
					"created_at": "2020-05-12T11:42:47.383001Z",
					"recipients": "all",
					"type": "filled_form",
					"properties": {
						"property_namespace": {
							"property_name": "property_value"
						}
					},
					"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
					"custom_id": "gh4ocmtv83w",
					"form_id": "1002",
					"fields": [
						{
							"id": "10021",
							"type": "name",
							"label": "Name and Surname:",
							"answer": "Thomas Anderson"
						},
						{
							"id": "10022",
							"type": "email",
							"label": "E-mail:",
							"answer": ""
						}
					]
				}
			],
			"properties": {
				"property_namespace": {
					"property_name": "property_value"
				}
			},
			"access": {
				"group_ids": [
					0
				]
			},
			"previous_thread_id": "QA078URPJL"
		}
	],
	"users": [
		{
			"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"name": "Thomas Anderson",
			"events_seen_up_to": "2020-05-12T12:31:46.463000Z",
			"type": "customer",
			"present": true,
			"created_at": "2019-11-02T19:19:50.625101Z",
			"last_visit": {
				"started_at": "2020-05-12T11:32:03.497479Z",
				"ip": "<customer_ip>",
				"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36",
				"geolocation": {
					"country": "Poland",
					"country_code": "PL",
					"region": "Dolnoslaskie",
					"city": "Wroclaw",
					"timezone": "Europe/Warsaw",
					"latitude": "51.1043015",
					"longitude": "17.0335007"
				},
				"last_pages": [
					{
						"opened_at": "2020-05-12T11:32:03.497479Z",
						"url": "https://cdn.livechatinc.com/preview/11442778",
						"title": "Sample Page | Preview your chat window"
					}
				]
			},
			"statistics": {
				"chats_count": 1,
				"threads_count": 3,
				"visits_count": 6,
				"page_views_count": 2,
				"greetings_shown_count": 2,
				"greetings_accepted_count": 1
			},
			"agent_last_event_created_at": "2020-05-12T11:42:47.393002Z",
			"customer_last_event_created_at": "2020-05-12T12:31:46.463000Z"
		},
		{
			"id": "smith@example.com",
			"name": "Agent Smith",
			"email": "smith@example.com",
			"events_seen_up_to": "2020-05-12T12:31:46.999999Z",
			"type": "agent",
			"present": false,
			"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png"
		}
	],
	"properites": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"access": {
		"group_ids": [
			1,
			2
		]
	},
	"is_followed": true
}
FieldReq./Opt.Note
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_thread_summary and last_event_per_type.

Sample Chat summary data structure
Copied!
{
	"id": "PJ0MRSHTDG",
	"last_thread_summary": {
		"id": "QA37PVJ75B",
		"created_at": "2020-05-12T11:42:47.383000Z",
		"user_ids": [
			"smith@example.com",
			"b7eff798-f8df-4364-8059-649c35c9ed0c"
		],
		"properties": {
			"property_namespace": {
				"property_name": "property_value"
			}
		},
		"active": false,
		"access": {
			"group_ids": [
				0
			]
		},
		"queue": {
			"position": 42,
			"wait_time": 1337,
			"queued_at": "2020-05-12T11:42:47.383000Z"
		}
	},
	"users": [
		{
			"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"name": "Thomas Anderson",
			"events_seen_up_to": "2020-05-12T12:31:46.463000Z",
			"type": "customer",
			"present": true,
			"created_at": "2019-11-02T19:19:50.625101Z",
			"last_visit": {
				"started_at": "2020-05-12T11:32:03.497479Z",
				"ip": "<customer_ip>",
				"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36",
				"geolocation": {
					"country": "Poland",
					"country_code": "PL",
					"region": "Dolnoslaskie",
					"city": "Wroclaw",
					"timezone": "Europe/Warsaw",
					"latitude": "51.1043015",
					"longitude": "17.0335007"
				},
				"last_pages": [
					{
						"opened_at": "2020-05-12T11:32:03.497479Z",
						"url": "https://cdn.livechatinc.com/preview/11442778",
						"title": "Sample Page | Preview your chat window"
					}
				]
			},
			"statistics": {
				"chats_count": 1,
				"threads_count": 3,
				"visits_count": 6,
				"page_views_count": 2,
				"greetings_shown_count": 2,
				"greetings_accepted_count": 1
			},
			"agent_last_event_created_at": "2020-05-12T11:42:47.393002Z",
			"customer_last_event_created_at": "2020-05-12T12:31:46.463000Z"
		},
		{
			"id": "smith@example.com",
			"name": "Agent Smith",
			"email": "smith@example.com",
			"events_seen_up_to": "2020-05-12T12:31:46.999999Z",
			"type": "agent",
			"present": false,
			"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png"
		}
	],
	"last_event_per_type": {
		"message": {
			"thread_id": "QA37PVJ75B",
			"thread_created_at": "2020-05-12T11:42:47.383000Z",
			"event": {
				"id": "QA37PVJ75B_1",
				"created_at": "2020-05-12T11:42:47.383000Z",
				"type": "message",
				"properties": {
					"property_namespace": {
						"property_name": "property_value"
					}
				},
				"text": "Hello",
				"author_id": "smith@example.com",
				"custom_id": "1589440960204.71699349177"
			}
		},
		"system_message": {
			"thread_id": "QA37PVJ75B",
			"thread_created_at": "2020-05-12T11:42:47.383000Z",
			"event": {
				"id": "QA37PVJ75B_3",
				"created_at": "2020-05-12T12:31:46.563000Z",
				"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
		]
	},
	"is_followed": 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": [
		"smith@example.com"
	],
	"restricted_access": "You can't access threads older than 60 days on starter plan",
	"events": [
		{
			"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
			"custom_id": "31-0C-1C-07-DB-16",
			"type": "message",
			"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"created_at": "2017-10-12T15:19:21.010200Z",
			"text": "Hello there",
			"recipients": "all"
		},
		{
			"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
			"custom_id": "31-0C-1C-07-DB-16",
			"type": "message",
			"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
			"created_at": "2017-10-12T15:19:21.010200Z",
			"text": "Thank you",
			"recipients": "all"
		}
	],
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"access": {
		"group_ids": [
			1,
			2
		]
	},
	"queue": {
		"position": 42,
		"wait_time": 1337,
		"queued_at": "2020-05-07T07:11:28.288340Z"
	},
	"queues_duration": 1337,
	"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 present.
propertiesoptional
restricted_accessoptionalContains the reason for access restriction.
queueoptionalPresent only if the chat is in the queue. Wait time is approximated in seconds.
queues_durationoptionalPresent only in the List Archives responses if the chat was queued.
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

GENERAL RTM API REQUEST FORMAT
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "payload": {
  // optional
  },
  "author_id": "<author_id>" // optional, applies only to bots
}
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 an Agent has access to.

Specifics
Actionlist_chats
Required scopes *chats--all:ro chats--access:ro chats--my:ro
Web API equivalentlist_chats
Push message-
Request
Request objectRequiredTypeNotes
filtersNoobjectMustn't change between requests for subsequent pages. Otherwise, the behavior is undefined.
filters.include_activeNoboolDefines if the returned chat summary includes active chats; default: true.
filters.include_chats_without_threadsNoboolDefines if the returned chat summary includes chats without any threads; default: true.
filters.group_idsNoarrayArray of group IDs. Max array size: 200
filters.properties.<namespace>.<name>.<filter_type>Noany
sort_orderNostringPossible values: asc - oldest chats firstm desc - newest chats first (default)
limitNonumberDefault: 10, maximum: 100
page_idNostring

filter_type can take the following values:

  • exists (bool)
  • values (type[] - array with specific type for property: string, int, or bool)
  • exclude_values (type[] - array with specific type for property: string, int, or bool)

There's only one value allowed for a single property.

Response
ParameterData typeNotes
chats_summaryarrayAn array of Chat summary data structures
next_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's a next page.
previous_page_idstringIn relation to page_id specified in the request Appears in the response only when there's a previous page.
found_chatsnumberAn estimated number. The real number of found chats can slightly differ.
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==", // optional
    "chats_summary": [{
      "id": "PJ0MRSHTDG",
      "last_event_per_type": {
        "message": {
          "thread_id": "K600PKZON8",
          "thread_created_at": "2020-05-07T07:11:28.288340Z",
          "event": {
            "id": "Q298LUVPRH_1",
            "created_at": "2019-12-09T12:01:18.909000Z",
            "recipients": "all",
            "type": "message",
            "text": "hello world",
            "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
          }
        },
        "system_message": {
          "thread_id": "K600PKZON8",
          "thread_created_at": "2020-05-07T07:11:28.288340Z",
          "event": {
            // "System message" event
          }
        }
      },
      "users": [{
        // "Customer" user object
      }, {
        // "Agent" user object
      }],
      "last_thread_summary": {
        "id": "K600PKZON8",
        "created_at": "2020-05-07T07:11:28.288340Z",
        "user_ids": [
          "b7eff798-f8df-4364-8059-649c35c9ed0c",
          "smith@example.com"
        ],
        "properties": {
          // "Properties" object
        },
        "active": true,
        "access": {
          "group_ids": [0]
        }
      },
      "properties": {
        // "Properties" object
      },
      "access": {
        "group_ids": [0]
      },
      "is_followed": true
    }],
    "found_chats": 4
  }
}

List Threads

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

Specifics
Actionlist_threads
Required scopeschats--all:ro chats--access:ro chats--my:ro
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>", // optional
  "action": "list_threads",
  "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",
        "smith@example.com"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "recipients": "all",
        "type": "message",
        "text": "Hello",
        "author_id": "smith@example.com"
      }],
      "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

It returns a thread that the current Agent has access to in a given chat.

Specifics
Actionget_chat
Required scopeschats--all:ro chats--access:ro chats--my:ro
Web API equivalentget_chat
Push message-
Request
ParameterRequiredData typeNotes
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",
        "smith@example.com"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "recipients": "all",
        "type": "message",
        "text": "Hello",
        "author_id": "smith@example.com"
      }],
      "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,
      "created_at": "2019-12-17T08:53:20.693553+01:00",
      "statistics": {
        "chats_count": 1
      },
      "agent_last_event_created_at": "2019-12-17T09:04:05.239000+01:00"
    }, {
      "id": "smith@example.com",
      "name": "Agent Smith",
      "email": "smith@example.com",
      "type": "agent",
      "present": true,
      "avatar": "https://example.com/avatar.jpg"
    }],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string_value"
      }
    },
    "access": {
      "group_ids": [0]
    },
    "is_followed": true
  }
}

List Archives

It returns a list of the chats an Agent has access to. Together with a chat, the events of one thread from this chat are returned.

The list classification is based on threads; 1 chat per 1 thread. Thus, the same chat object may appear on the list several times, but each time with a different thread. The returned chat is a complete object, not only a chat summary.

Specifics
Actionlist_archives
Required scopeschats--all:ro chats--access:ro chats--my:ro
Web API equivalentlist_archives
Push message-
Request
ParameterRequiredData typeNotes
filtersNoobject
filters.queryNostring
filters.fromNostringDate & time format with a resolution of microseconds, UTC string, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM
filters.toNostringDate & time format with a resolution of microseconds, UTC string, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM
filters.group_idsNoarrayArray of group IDs. Max array size: 200
filters.properties.<namespace>.<name>.<filter_type>Noany* described below
filters.agents.<filter_type>Noanyexists see to false will return unassigned chats; true will return the assigned ones.
filters.tags.<filter_type>Noany
filters.sales.<filter_type>Noany
filters.goals.<filter_type>Noany
filters.surveys.<survey>Noarray** described below
filters.events.typesNoarrayArray of Event types. Duplicates are ignored.
page_idNostring
sort_order ***NostringDefault: desc
limitNonumberDefault: 10, min: 1, max: 100
highlightsNoobjectUse it to highlight the match of filters.query. To enable highlights with default parameters, pass an empty object.
highlights.pre_tagNostringAn HTML tag to use for highlighting the matched text; default: <em>. Use it together with highlights.post_tag.
highlights.post_tagNostringAn HTML tag to use for highlighting the matched text; default: </em>. Use it together with highlights.pre_tag.

*) <filter_type> can take the following values:

  • exists (bool)
  • values (type[] - an array with aspecific type for property: string, int or bool)
  • exclude_values (type[] - array with specific type for property: string, int or bool)

There's only one value allowed for a single property.

**) <survey> contains the following fields:

  • type (string) - allowed values: pre_chat, post_chat
  • answer_id (string)

***) sort_order can take the following values:

  • asc - the oldest chats first
  • desc - the newest chats first
REQUEST
Copied!
{
  "action": "list_archives",
  "payload": {
    "filters": {
      "events": {
        "types": ["message", "filled_form"]
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>",
  "action": "list_archives",
  "type": "response",
  "success": true,
  "payload": {
    "chats": [
      {
        "id": "PJ0MRSHTDG",
        "users": [
          {
            "id": "smith@example.com",
            "name": "Agent Smith",
            "email": "smith@example.com",
            "type": "agent",
            "present": true,
            "avatar": "https://cdn.livechatinc.com/cloud/?uri=avatar.jpg"
          }
        ],
        "thread": {
          "id": "K600PKZON8",
          "active": false,
          "user_ids": [
            "smith@example.com"
          ],
          "events": [
            {
              "id": "QBT14H0Y3Y_1",
              "created_at": "2020-05-28T11:45:32.269000Z",
              "recipients": "all",
              "type": "message",
              "properties": {
                "0805e283233042b37f460ed8fbf22160": {
                  "event_property": "property_value"
                }
              },
              "text": "Hello, how can I help you?",
              "author_id": "smith@example.com"
            }
          ],
          "properties": {
            "0805e283233042b37f460ed8fbf22160": {
              "thread_property": "property_value"
            }
          },
          "access": {
            "group_ids": [
              0
            ]
          },
          "created_at": "2020-05-28T11:44:58.829000Z"
        },
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "chat_property": "property_value"
          }
        },
        "access": {
          "group_ids": [
            0
          ]
        },
        "is_followed": false
      }
    ],
    "found_chats": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "previous_page_id": "MTUxNzM5ODEzMTQ5Ng=="
  }
}

Start Chat

Starts a chat.

Specifics
Actionstart_chat
Required scopes *chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentstart_chat
Push messageincoming_chat

*) When chat.users is defined, one of following scopes is required:

  • chats--all:rw
  • chats--access:rw
  • chats--my:rw
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobject
chat.accessNoobject
chat.usersNo[]objectThe list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
chat.users.idYesstringUser ID
chat.users.typeYesstringagent or customer.
chat.threadNoobject
chat.thread.eventsNoarrayThe list of initial chat events
chat.thread.propertiesNoobject
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

Restarts an archived chat.

Specifics
Actionactivate_chat
Required scopes *chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentactivate_chat
Push messageincoming_chat

*) When chat.users is defined, one of following scopes is required:

  • chats--all:rw
  • chats--access:rw
  • chats--my:rw
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.usersNo[]objectThe list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
chat.users.idYesstringUser ID
chat.users.typeYesstringagent or customer
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": "<action>",
  "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
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentdeactivate_chat
Push messagechat_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
  }
}

Follow Chat

Marks a chat as followed. All changes to the chat will be sent to the requester until the chat is reactivated or unfollowed. Chat members don't need to follow their chats. They receive all chat pushes regardless of their follower status.

Specifics
Actionfollow_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentfollow_chat
Push messageincoming_chat*

*) It won't be sent when the requester already follows the chat or is the chat member.

Request
ParameterRequiredData type
chat_idYesstring
REQUEST
Copied!
{
  "action": "follow_chat",
  "payload": {
  "chat_id": "PW94SJTGW6"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "follow_chat",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Unfollow Chat

Removes the requester from the chat followers. After that, only key changes to the chat (like transfer_chat or close_active_thread) will be sent to the requester. Chat members cannot unfollow the chat.

Specifics
Actionunfollow_chat
Required scopes-
Web API equivalentunfollow_chat
Push messagechat_unfollowed
Request
ParameterRequiredData type
chat_idYesstring
REQUEST
Copied!
{
  "action": "unfollow_chat",
  "payload": {
  "chat_id": "PWF6BACIKO"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "unfollow_chat",
  "type": "response",
  "success": true,
  "payload": {
  "chat_id": "PWF6BACIKO"
  }
}

Chat access

Grant Chat Access

Grants access to a new chat without overwriting the existing ones.

Specifics
Actiongrant_chat_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentgrant_chat_access
Push messagechat_access_granted
Request
ParameterRequiredData ypeNotes
idYesstringChat Id
accessYesobject
access.typeYesstringgroup
access.idYesany
REQUEST
Copied!
{
  "action": "grant_chat_access",
  "payload": {
  "id": "PW94SJTGW6",
  "access": {
    "type": "group",
    "id": 19
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "grant_chat_access",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Revoke Chat Access

Specifics
Actionrevoke_chat_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentrevoke_chat_access
Push messagechat_access_revoked
Request
ParameterRequiredData typeNotes
idYesstringChat Id
accessYesobject
access.typeYesstringgroup or agent
access.idYesnumber
REQUEST
Copied!
{
  "action": "revoke_chat_access",
  "payload": {
  "id": "PW94SJTGW6",
  "access": {
    "type": "group",
    "id": 19
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "revoke_chat_access",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Transfer Chat

Transfers a chat to an Agent or a group.

Specifics
Actiontransfer_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalenttransfer_chat
Push messagechat_transferred
Request
ParameterRequiredData ypeNotes
chat_idYesstringChat Id
targetNoobjectIf missing, the chat will be transferred within the current group.
target.typeYesstringgroup or agent
target.idsYesarraygroup or agent IDs array
forceNoboolIf true, always transfers chats. Otherwise, fails when unable to assign any Agent from the requested groups; default false.
REQUEST
Copied!
{
  "action": "transfer_chat",
  "payload": {
  "chat_id": "PWF6BACIKO",
  "target": {
    "type": "group",
    "ids": [19]
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "transfer_chat",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Chat users

Add User to Chat

Adds a user to the chat. You can't add more than one customer user type to the chat.

Specifics
Actionadd_user_to_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentadd_user_to_chat
Push messageuser_added_to_chat
Request
Request objectRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible values: agent or customer
require_active_threadNoboolIf true, it adds a user to a chat only if that chat has an active thread; default false.
REQUEST
Copied!
{
  "action": "add_user_to_chat",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "user_id": "smith@example.com",
  "user_type": "agent",
  "require_active_thread": "true"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "add_user_to_chat",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Remove User from Chat

Removes a user from chat. Removing customer user type is not allowed. It's always possible to remove the requester from chat.

Specifics
Actionremove_user_from_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentremove_user_from_chat
Push messageuser_removed_from_chat
Request
Request objectRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible values are agent or customer
REQUEST
Copied!
{
  "action": "remove_user_from_chat",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "user_id": "smith@example.com",
  "user_type": "agent"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "remove_user_from_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.

It's possible to write to a chat without joining it. The user sending an event will be automatically added to the chat with the present parameter set to false (see user_added_to_chat). Sample use case: a Bot Agent that sends messages visible to all chat participants without actually joining the chat.

Specifics
Actionsend_event
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentsend_event
Push messageincoming_event
Request
ParametersRequiredData typeNotes
chat_idYesstringId of the chat you want to send the message to.
eventYesobjectEvent object
attach_to_last_threadNoboolIf true, adds an event to 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
Required scopeschats.conversation--my:rw chats.conversation--all:rw
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
  }
}

Properties

Update Chat Properties

Specifics
Actionupdate_chat_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
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": "Q1VZR7AJCE",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat property value updated by Agent"
      }
    }
  }
}
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
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentdelete_chat_properties
Push messagechat_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete property for.
propertiesYesobjectChat properties to delete.
REQUEST
Copied!
{
  "action": "delete_chat_properties",
  "payload": {
  "chat_id": "Q1VZR7AJCE",
  "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
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
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": "Q1WZ073OA7",
  "thread_id": "Q1WZ073OB7",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat thread property value updated by Agent"
      }
    }
  }
}
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
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentdelete_thread_properties
Push messagethread_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete property for.
thread_idYesstringId of the thread you want to delete property for.
propertiesYesobjectChat properties to delete.
REQUEST
Copied!
{
  "action": "delete_thread_properties",
  "payload": {
   "chat_id": "Q1WZ073OA7",
   "thread_id": "Q1WZ073OB7",
   "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
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
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.
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 Agent"
      }
    }
  }
}
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
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
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. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "delete_event_properties",
  "payload": {
  "chat_id": "Q16ZSBGX3J",
  "thread_id": "Q16ZSBGX4J",
  "event_id": "Q16ZSBGX4J_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_event_properties",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Thread tags

Tag Thread

Specifics
Actiontag_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalenttag_thread
Push messagethread_tagged
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to add a tag to.
thread_idYesstringId of the thread you want to add a tag to.
tagYesstringTag name
REQUEST
Copied!
{
  "action": "tag_thread",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "tag_thread",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Untag Thread

Specifics
Actionuntag_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
Web API equivalentuntag_thread
Push messagethread_untagged
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to remove a tag from.
thread_idYesstringId of the thread you want to remove a tag from.
tagYesstringTag name
REQUEST
Copied!
{
  "action": "untag_thread",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "untag_thread",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Customers

Get Customer

Returns the info about the Customer with a given customer_id.

Specifics
Actionget_customer
Required scopescustomers:ro
Web API equivalentget_customer
Push message-
Request
ParameterRequiredData typeNotes
customer_idYesstring
Response
ParameterData typeNotes
idstringCustomer's ID.
typestringcustomer
namestringCustomer's name. Returned only if set.
emailstringCustomer's email. Returned only if set.
avatarstringCustomer's avatar. Returned only if set.
created_atstringSpecifies when the customer's identity was created.
session_fields[]objectAn array of custom object-enclosed key:value pairs. Returned only if set. Available for the session duration.
statisticsobjectCounters for started threads, opened pages, etc.
last_visitobjectGeolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once.
chat_ids[]stringIDs of a customer's chats. Returned only if the customer had at least one chat.
REQUEST
Copied!
{
  "action": "get_customer",
  "payload": {
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_customer",
  "type": "response",
  "success": true,
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "type": "customer",
    "created_at": "2017-10-11T15:19:21.010200Z",
    "name": "Thomas Anderson",
    "email": "t.anderson@example.com",
    "avatar": "example.com/avatars/1.jpg",
    "session_fields": [{
      "custom_key": "custom_value"
    }, {
      "another_custom_key": "another_custom_value"
    }],
    "last_visit": {
      "started_at": "2017-10-12T15:19:21.010200Z",
      "referrer": "http://www.google.com/",
      "ip": "<customer_ip>",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
      "geolocation": {
        "latitude": "-14.6973803",
        "longitude": "-75.1266898",
        "country": "Poland",
        "country_code": "PL",
        "region": "Dolnoslaskie",
        "city": "Wroclaw",
        "timezone": "Europe/Warsaw"
      },
      "last_pages": [{
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.livechatinc.com/",
        "title": "LiveChat - Homepage"
      }, {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.livechatinc.com/tour",
        "title": "LiveChat - Tour"
      }]
    },
    "statistics": {
      "chats_count": 3,
      "threads_count": 9,
      "visits_count": 5,
      "page_views_count": 1337,
      "greetings_shown_count": 69,
      "greetings_accepted_count": 42
    },
    "__priv_lc2_customer_id": "test_771305.dafea66e5c", // old customer_id
    "agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
    "customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
    "chat_ids": [
      "PWJ8Y4THAV"
    ]
  }
}

List Customers

It returns the list of Customers.

Specifics
Actionlist_customers
Required scopescustomers:ro
Web API equivalentlist_customers
Push message-
Request

All parameters are optional.

ParameterData typeNotes
page_idstring
limitnumberDefault: 10, maximum: 100
sort_order *stringDefault: desc
filtersobject
filters.country.<string_filter_type> **object
filters.email.<string_filter_type> **object
filters.name.<string_filter_type> **object
filters.customer_id.<string_filter_type> **object
filters.chats_count.<range_filter_type> ***object
filters.threads_count.<range_filter_type> ***object
filters.visits_count.<range_filter_type> ***object
filters.created_at.<date_range_filter_type>****object
filters.agent_last_event_created_at.<date_range_filter_type> ****object
filters.customer_last_event_created_at.<date_range_filter_type> ****object

*)

sort_order can take the following values:

  • asc - oldest customers first
  • desc - newest customers first

**)

<string_filter_type> can take the following values :

  • values (string[] - an array of strings)
  • exclude_values (string[] - an array of strings)

There's only one value allowed for a single filter.

***)

<range_filter_type> can take the following values:

  • lte (int - less than or equal to given value)
  • lt (int - less than given value)
  • gte (int - greater than or equal to given value)
  • gt (int - greater than given value)
  • eq (int - equal to given value)

****)

<date_range_filter_type> can take the following values:

  • lte ( string - less than or equal to given value)
  • lt (string - less than given value)
  • gte (string - greater than or equal to given value)
  • gt (string - greater than given value)
  • eq (string - equal to given value)

Dates are represented in ISO 8601 format with microseconds resolution, e.g. 2017-10-12T15:19:21.010200+01:00 in specific timezone or 2017-10-12T14:19:21.010200Z in UTC.

Response
ParameterData typeNotes
next_page_idstringIn relation to page_id specified in the request.
previous_page_idstringIn relation to page_id specified in the request.
REQUEST
Copied!
{
  "action": "list_customers",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "list_customers",
  "type": "response",
  "success": true,
  "payload": {
  "customers": [
    // an array of "User > Customer" objects
  ],
  "total_customers": 2340,
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Ng==" // optional
  }
}

Create Customer

Creates a new Customer user type.

Specifics
Actioncreate_customer
Required scopescustomers:rw
Web API equivalentcreate_customer
Push messagecustomer_created
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.
REQUEST
Copied!
{
  "action": "create_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": "create_customer",
  "type": "response",
  "success": true,
  "payload": {
   "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

Update Customer

Updates Customer's properties.

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

Apart from customer_id, which is a required parameter, you also need to include one of the optional parameters.

REQUEST
Copied!
{
  "action": "update_customer",
  "payload": {
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "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
  }
}

Ban Customer

Bans the customer for a specific period of time. It immediately disconnects all active sessions of this customer and does not accept new ones during the ban lifespan.

Specifics
Actionban_customer
Required scopescustomers.ban:rw
Web API equivalentban_customer
Push messagecustomer_banned
Request
ParameterRequiredData type
customer_idYesstring
banYesobject
ban.daysYesnumber
REQUEST
Copied!
{
  "action": "ban_customer",
  "payload": {
  "customer_id": "3cd19fff-f852-4402-59ce-ebd03af3f15a",
  "ban": {
    "days": 3
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "ban_customer",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Status

Login

It returns the initial state of the current Agent.

Specifics
Actionlogin
Required scopeschats--access:ro customers:ro multicast:ro agents--all:ro agents-bot--all:ro
Web API equivalent-
Push message-
Request
ParameterRequiredData typeNotes
tokenYesstringOAuth token from the Agent's account
timezoneNostring
reconnectNoboolReconnecting sets the status to the last known state instead of the default one.
push_notificationsNoobject
push_notifications.firebase_tokenNostringFirebase device token to allow connecting this instance with the existing push notification instance (to be seen as 1 instance).
push_notifications.platformYesstringOS platform; possible values:ios, android. Required only when push_notifications is included.
applicationNoobject
application.nameNostringApplication name
application.versionNostringApplication version
away *NoboolWhen true, the connection is set to the away state. Defaults to false.

* You can use the away param to prevent assigning chats to Agents after random reconnections when their status was set to not_accepting_chats by the auto-away feature. When an Agent logs in with away: true, the connection is immediately recognized as away. Read more...

Response
ParameterData typeNotes
accessobject
propertiesobject
REQUEST
Copied!
{
  "action": "login",
  "payload": {
    "token": "Bearer dal:test_1fgTbfXmgthj4cZSA"
    }
  }
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "login",
  "type": "response",
  "success": true,
  "payload": {
  "license": {
    "id": "104130623",
    "plan": "enterprise",
    "expiration_timestamp": 1483433500,
    "creation_timestamp": 1482433500,
    "in_trial": true,
    "website_last_activity": "2018-01-05" // optional
  },
  "my_profile": {
    // "User > My profile" object
  },
  "chats_summary": [{
    "id": "PJ0MRSHTDG",
    "users": [
    // array of "User" objects
    ],
    "last_event_per_type": {
    // the last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_created_at": "2020-05-07T07:11:28.288340Z",
      "event": {
      // "restricted_access": "User has no access to following resource"
      // or
      // Event > Message object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON8",
      "thread_created_at": "2020-05-07T07:11:28.288340Z",
      "event": {
      // "restricted_access": "User has no access to following resource"
      // or
      // Event > System Message object
      }
    }
    // ...
    },
    "last_thread_summary": {
    "id": "K600PKZON8",
    "user_ids": ["smith@example.com"],
    "properties": {
      "routing": {
      "idle": false,
      "unassigned": false
      }
      // ...
    },
    "created_at": "2020-05-07T07:11:28.288340Z"
    },
    "properties": {
    "routing": {
      "idle": false,
      "unassigned": false
    }
    // ...
    },
    "access": {
    // "Access" object
    }
  }]
  }
}

Set Away Status

Sets an Agent's connection to the away state. You can use this method to manipulate the Agent's status. The method works per connection - all connections an Agent has (desktop, mobile, etc) must be in the away state for the Agent's status to be changed to not_accepting_chats.

You may want to make use of the auto-away feature and set the Agents' statuses to not_accepting_chats when they're inactive, for example they're not at their desks. Remember that checking if Agents are active/inactive should be implemented on your side. If you decide they're inactive, set their connections to away. The auto-away feature will recognize the away connections and change the Agent's status to not_accepting_chats.

Specifics
Actionset_away_status
Required scopesagents--my:rw
Web API equivalent-
Push message-
Request
Request objectRequiredData type
awayYesbool
REQUEST
Copied!
{
  "action": "set_away_status",
  "payload": {
  "away": true
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "set_away_status",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Change Push Notifications

Change the firebase push notifications properties.

Specifics
Actionchange_push_notifications
Required scopes-
Web API equivalent-
Push message-
Request
ParameterRequiredData typeNotes
firebase_tokenYesstringFirebase device token
platformYesstringOS platform; possible values: ios, android
enabledYesboolEnable or disable push notifications for the requested token
REQUEST
Copied!
{
  "action": "change_push_notifications",
  "payload": {
  "firebase_token": "8daDAD9dada8ja1JADA11",
  "platform": "ios",
  "enabled": true
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "change_push_notifications",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Set Routing Status

Changes the status of an Agent or a Bot Agent. It sets the status for the session duration. Once the session ends, the status gets back to what's in the Agent's settings. Unlike Set Away Status, which is another mechanism of status manipulation, Set Routing Status is independent of the number of connections (desktop, mobile, etc).

Specifics
Actionset_routing_status
Required scopesfor Agents: agents--my:rw agents--all:rw; for Bot Agents: agents-bot--my:rw agents-bot--all:rw
Web API equivalentset_routing_status
Push messagerouting_status_set
Request
ParameterRequiredData typeNotes
statusYesstringFor Agents: accepting_chats or not_accepting_chats; for Bot Agents: accepting_chats, not_accepting_chats, or offline
agent_idNostringIf not specified, the requester's status will be updated.
REQUEST
Copied!
{
  "action": "set_routing_status",
  "payload": {
  "status": "accepting_chats",
  "agent_id": "smith@example.com"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "set_routing_status",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Logout

Logs the Agent out.

Specifics
Actionlogout
Required scopes-
Web API equivalent-
Push message-
REQUEST
Copied!
{
  "action": "logout",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "logout",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Other

Mark Events as Seen

Specifics
Actionmark_events_as_seen
Required scopeschats--access:ro chats--all:ro
Web API equivalentmark_events_as_seen
Push messageevents_marked_as_seen
Request
ParameterRequiredData typeNotes
chat_idYesstring
seen_up_toYesstringRFC 3339 date-time format
REQUEST
Copied!
{
  "action": "mark_events_as_seen",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "seen_up_to": "2017-10-12T15:19:21.010200Z"
  }
}
Response
Copied!
{
  "request_id": "<request_id>",
  "action": "mark_events_as_seen",
  "type": "response",
  "success": true,
  "payload": {
  }
}

Send Typing Indicator

Specifics
Actionsend_typing_indicator
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
Web API equivalentsend_typing_indicator
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to send the typing indicator to.
recipientsNostringall (default), agents
is_typingYesbool
REQUEST
Copied!
{
  "action": "send_typing_indicator",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "is_typing": true
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_typing_indicator",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

Multicast

This method serves for the chat-unrelated communication. Messages sent using multicast are not being saved.

For example, it could be used in an app that sends notifications to Agents or Customers, when a certain condition is met (e.g. an important Customer started the chat).

Specifics
Actionmulticast
Required scopesmulticast:rw
Web API equivalentmulticast
Push messageincoming_multicast
Request
ParameterRequiredData typeNotes
recipientsYesobject*
contentYesanyA JSON message to be sent
typeNostringMulticast message type

*) recipients can take the following values:

  • agents:

    • all (bool - includes all agents)
    • ids ([]string - an array of agents' IDs)
    • groups ([]string - an array of groups' IDs)
  • customers:

    • ids ([]string - an array of customer's IDs)

At least one recipients type (agents.all, agents.ids, agents.groups, customers.ids) is required.

REQUEST
Copied!
{
  "action": "multicast",
  "payload": {
  "recipients": {
    "agents": {
    "all": true,
    "ids": [
      "smith@example.com",
      "agent@example.com"
    ],
    "groups": [
      1,
      2
    ]
    },
    "customers": {
    "ids": [
      "b7eff798-f8df-4364-8059-649c35c9ed0c"
    ]
    }
  },
  "content": {
    "example": {
    "nested": "json"
    }
  }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "multicast",
  "type": "response",
  "success": true,
  "payload": {
  // no response payload
  }
}

List Agents For Transfer

It returns the Agents you can transfer a chat to. Agents are sorted ascendingly by the total number of active chats they have. Note that:

  • The method only returns Agents with statuses online and not accepting chats. Offline Agents aren't returned.
  • Only chats with Customers are taken into account in total_active_chats.
Specifics
Actionlist_agents_for_transfer
Required scopes-
Web API equivalentlist_agents_for_transfer
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstringThe ID of the chat you want to transfer
REQUEST
Copied!
{
  "action": "list_agents_for_transfer",
  "payload": {
   "chat_id": "PJ0MRSHTDG"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "list_agents_for_transfer",
  "type": "response",
  "success": true,
  "payload": [{
  "agent_id": "smith@example.com",
  "active_chats": 2
  }, {
  "agent_id": "agent@example.com",
  "active_chats": 5
  }]
}

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 user has seen an event, compare the event's created_at parameter with the user's events_seen_up_to field.
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": "smith@example.com",
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [
      // array of "User" objects
    ],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
      "string_property": "string value"
      }
      // ...
    },
    "thread": {
      // "Thread" object
    },
    "transferred_from": {
      "group_ids": [ 1 ],
      "agent_ids": [ "agent@example.com" ]
    }
  }
}
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_access_granted

Informs that new, single access to a chat was granted. The existing access isn't overwritten.

Sample push payload
Copied!
{
  "id": "PJ0MRSHTDG",
  "access": {
  "group_ids": [1]
  }
}
Specifics
Actionchat_access_granted
Webhook equivalentchat_access_granted
Push payload
ObjectNotes
idChat id

chat_access_revoked

Informs that access to a certain chat was revoked.

Sample push payload
Copied!
{
  "id": "PJ0MRSHTDG",
  "access": {
  "group_ids": [1]
  }
}
Specifics
Actionchat_access_revoked
Webhook equivalentchat_access_revoked
Push payload
ObjectNotes
idChat Id

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": "cb531744-e6a4-4ded-b3eb-b3eb4ded4ded",
  "transferred_to": {
    "group_ids": [ 1 ],
    "agent_ids": ["smith@example.com"],
  },
  "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_to *IDs of groups and Agents the chat is now assigned to
queuePresent if the chat is queued after the transfer

*) One of the following combinations of IDs is possible:

  • Both group_ids and agent_ids. In situations when a chat was transferred to a group and it was immediately assigned to an Agent (even if the chat transfer occurred in the same group).
  • Only group_ids. When a chat was transferred to a group and no Agents were available; the queue will be present.
  • Only agent_ids. When a chat was transferred directly to an Agent; there'll be no queue.

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": "smith@example.com"
}
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": "agent@example.com",
  "reason": "manual",
  "requester_id": "smith@example.com"
}
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": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}
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": "PJ0MRSHTDG",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  // ...
  }
}
Specifics
Actionchat_properties_updated
Webhook equivalentchat_properties_updated
Push payload
ObjectNotes
propertiesThis is 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
Specifics
Actionchat_properties_deleted
Webhook equivalentchat_properties_deleted
Push payload
ObjectNotes
propertiesThis is not 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": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  // ...
  }
}
Specifics
Actionthread_properties_updated
Webhook equivalentthread_properties_updated
Push payload
ObjectNotes
propertiesThis is not a full properties object. This push shows only the properties that have been recently updated.

thread_properties_deleted

Informs about those thread properties that were deleted.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
}
Specifics
Actionthread_properties_deleted
Webhook equivalentthread_properties_deleted
Push payload
ObjectNotes
propertiesThis is 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  }
}
Specifics
Actionevent_properties_updated
Webhook equivalentevent_properties_updated
Push payload
ObjectNotes
propertiesThis is 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
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.

Thread tags

thread_tagged

Informs that a chat thread was tagged.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "tag": "bug_report"
}
Specifics
Actionthread_tagged
Webhook equivalentthread_tagged

thread_untagged

Informs that a chat thread was untagged.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "tag": "bug_report"
}
Specifics
Actionthread_untagged
Webhook equivalentthread_untagged

Customers

customer_visit_started

Informs that a Customer entered the tracked website.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "started_at": "2017-10-12T15:19:21.010200Z",
  "ip": "<customer_ip>",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
  "geolocation": {
    "latitude": "54.0805",
    "longitude": "17.4211",
    "country": "Poland",
    "country_code": "PL",
    "region": "Dolnoslaskie",
    "city": "Wroclaw",
    "timezone": "Europe/Warsaw"
  }
}
Specifics
Actioncustomer_visit_started
Webhook equivalent-

customer_created

Informs that a new Customer registered.

Sample push payload
Copied!
{
  "customer": {
  // "User > Customer" object
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2019-11-14T14:27:24.410018Z",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "https://example.com/avatars/1.jpg",
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }]
  }
}
Specifics
Actioncustomer_created
Webhook equivalentcustomer_created

customer_updated

Informs that Customer's data was updated.

Sample push payload
Copied!
{
  "customer": {
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "https://example.com/avatars/1.jpg",
  "type": "customer",
  "present": false,
  "banned": false,
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }]
  }
}
Specifics
Actioncustomer_updated
Webhook equivalent-

customer_page_updated

Informs that a Customer moved to another page of the website.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "opened_at": "2017-10-12T15:19:21.010200Z",
  "url": "https://www.livechatinc.com/",
  "title": "LiveChat - Homepage",
  "referrer": "http://www.google.com/"
}
Specifics
Actioncustomer_page_updated
Webhook equivalent-

customer_banned

Informs that a Customer was banned for a specified number of days.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "ban": {
  "days": 5
  }
}
Specifics
Actioncustomer_banned
Webhook equivalent-

customer_visit_ended

Informs that a Customer left the tracked website.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "ended_at": "2017-10-12T15:19:21.010200Z"
}
Specifics
Actioncustomer_visit_ended
Webhook equivalent-

Status

routing_status_set

Informs that an Agent's or Bot Agent's status was changed.

Sample push payload
Copied!
{
  "agent_id": "smith@example.com",
  "status": "accepting_chats"
}
Specifics
Actionrouting_status_set
Webhook equivalentrouting_status_set

agent_disconnected

Informs that an Agent was disconnected. The payload contains the reason of Customer's disconnection.

Sample push payload
Copied!
{
  "reason": "misdirected_request",
  "data": {
  // optional
  "region": "fra"
  }
}
Specifics
Actionagent_disconnected
Webhook equivalent-
Possible reasons
TypeNotes
access_token_revokedAgent access token has been revoked.
access_token_expiredAccess token life time has elapsed.
license_expiredLicense has expired.
agent_deletedAgent account has been deleted.
agent_logged_out_remotelyAgent has been logged out remotely.
agent_disconnected_by_serverAgent has been disconnected by the server.
unsupported_versionConnecting to an unsupported version of the Agent API.
ping_timeoutNot receiving ping for some time from the Customer.
internal_errorInternal error
too_many_connectionsAgent reached the max. number of connections.
misdirected_connection *Agent connected to the server in the wrong region.
product_version_changedProduct version has been changed.
license_not_foundLicense with the specified ID doesn't exist.

*) Also, misdirected_connection returns the correct region value in the optional data object. With this piece of information, the 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": "smith@example.com",
  "recipients": "all",
  "timestamp": 1574245378,
  "is_typing": true
  }
}
Specifics
Actionincoming_typing_indicator
Webhook equivalent-

incoming_sneak_peek

Informs about the message a Customer is currently typing. The push payload contains the sneak peek object.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "sneak_peek": {
  author_id: "b7eff798-f8df-4364-8059-649c35c9ed0c",
  recipients: "all",
  text: "Hello",
  timestamp: 1574245378
  }
}
Specifics
Actionincoming_sneak_peek
Webhook equivalent-

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_multicast

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

Sample push payload
Copied!
{
  "author_id": "smith@example.com",
  "content": {
  "example": {
    "nested": "json"
  }
  },
  "type": "type1"
}
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
typeNo

chat_unfollowed

Informs that a chat has been unfollowed. Useful in multiple connection scenarios, where one app/integration needs to know that another one unfollowed the chat.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG"
}
Specifics
Actionchat_unfollowed
Webhook equivalent-

queue_positions_updated

New positions and wait times for queued chats.

Sample push payload
Copied!
[{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "queue": {
    "position": 42,
    "wait_time": 1337
  }
}, {
  "chat_id": "PJ0VRSATDS",
  "thread_id": "K60QPKSON9",
  "queue": {
    "position": 43,
    "wait_time": 1373
  }
}]
Specifics
Actionqueue_positions_updated
Webhook equivalent-

Errors

Format of error payload
Copied!
{
  "error": {
  "type": "misdirected_request",
  "message": "Wrong region",
  "data": {
    // optional
    "region": "dal"
  }
  }
}

Possible errors

Error typeDefault messageDescription
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorUser is not allowed to perform the action.
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.
requester_already_offlineRequester offlineThe method is only allowed for the logged in Agents (via RTM API).
requester_awaiting_approvalRequester awaiting approvalA new Agent hasn't been approved by the license owner yet.
request_timeoutRequest timed outTimeout threshold is 15 seconds.
requester_suspendedRequester suspendedThe rights of a given Agent have been withdrawn by the license owner.
validationWrong format of request
wrong_product_versionWrong product versionLicense is not LiveChat 3 (probably still LiveChat 2).
seats_limit_exceededSeats limit exceededDisplayed on the attempt of logging in. All seats within a given license are already taken.
chat_inactiveNo active chat threadAn action that requires an active thread performed on a chat with no active threads.
too_many_requestsToo many requestsThe request's rate limit was exceeded. It'll be unblocked automatically after some time.

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!