RTM API Reference

Introduction

Versioning

This documentation describes the Agent Chat Real-Time Messaging API v3.3. This is the latest stable version recommended for the production use. Read more about versioning...

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

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

Pagination

Pagination is a mechanism that allows splitting the database output into more manageable chunks of data. Based on the limit and sort order parameters, pagination is able to decide how many records will be returned at once and whether it should fetch the oldest or the latest data first.

Any filters that could be applied should be provided in first pagination request. In the response, you'll get the next_page_id and previous_page_id parameters. You should make the subsequent request using one of these parameters as page_id, depending on the direction of iteration: forward or backward.

The filters, limit, and sort_order parameters can't be provided along with page_id.

💡 The maximum duration of the page_id parameter before it expires is one month.

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`recipients`	yes	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the LiveChat CDN. It's recommended to use the URL returned by `upload_file`.
`alternative_text`	no	`string`	Only applicable to images

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`recipients`	always
`properties`	optionally
`name`	always
`url`	always
`thumbnail_url`, `thumbnail2x_url`	only for images
`content_type`	always
`size`, `width`, `height`	only for images
`alternative_text`	only 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,
	"alternative_text": "A sample image"
}

Form

The Form event contains an empty form to be filled out by the customer. It doesn't matter how the form is configured or what fields it has – it can be any event of type form.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`form`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	optionally	If the form is generated by `system`, then this field is omitted.
`properties`	optionally
`form_id`	always
`fields`	always	An array of form fields

A sample use case: sending a form in the chat after a pre-determined agent's inactivity period. This could be a way of gathering contact info from customers so that the overloaded agent can contact them later.

Gather contact info with LiveChat form event

Sample Form in response

Copied!

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"type": "form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	},
	"form_id": "1473433500211",
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name",
			"required": true
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email",
			"required": false
		},
		{
			"type": "question",
			"id": "154417206262601585",
			"label": "What are you looking for?",
			"required": false
		},
		{
			"type": "textarea",
			"id": "154417206262601586",
			"label": "Additional info",
			"required": false
		},
		{
			"type": "radio",
			"id": "154417206262602571",
			"label": "Chat purpose",
			"required": false,
			"options": [
				{
					"id": "0",
					"label": "Support"
				}
			]
		},
		{
			"type": "select",
			"id": "154417206262602572",
			"label": "Country",
			"required": false,
			"options": [
				{
					"id": "0",
					"label": "USA"
				},
				{
					"id": "1",
					"label": "UK"
				}
			]
		},
		{
			"type": "checkbox",
			"id": "154417206262604640",
			"label": "Company industry",
			"required": false,
			"options": [
				{
					"id": "0",
					"label": "automotive"
				},
				{
					"id": "1",
					"label": "it"
				}
			]
		}
	]
}

Filled form

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

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`filled_form`
`recipients`	yes	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See filled form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`recipients`	always
`properties`	optionally
`form_id`	always
`fields`	always	The fields a form contains. See filled form fields for details.

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`text`	yes	`string`	Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
`type`	yes	`string`	`message`
`recipients`	yes	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`postback`	no	`object`	Indicates that the message event was generated in response to a rich message event.
`postback.id`	yes	`string`	ID of the postback from the rich message event.
`postback.thread_id`	yes	`string`	ID of the thread with the rich message event.
`postback.event_id`	yes	`string`	ID of the rich message event.
`postback.type`	no	`string`	Should be used together with `postback.value` (when one of them is present, the other is required).
`postback.value`	no	`string`	Should be used together with `postback.type` (when one of them is present, the other is required).

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always	`message`
`author_id`	always
`recipients`	always
`text`	always
`postback`	optionally	Appears in a message only when triggered by a rich message.
`postback.id`	always
`postback.thread_id`	always
`postback.event_id`	always
`postback.type`	optionally	Appears only if `postback.value` is present.
`postback.value`	optionally	Appears only if `postback.type` is present.
`properties`	optionally	Properties

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give your RM a custom ID.
`type`	yes	`string`	Event type: `rich_message`
`recipients`	yes	`string`	Those who can display the rich message: `all` (default) or `agents`
`properties`	no	`object`	The properties data structure
`template_id`	yes	`string`	Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`.
`elements`	no	`array`	Can contain up to 10 `element` objects.
`elements.title`	yes	`string`	Displays formatted text on RMs.
`elements.subtitle`	yes	`string`	Displays formatted text on RMs.
`elements.image`	yes	`image`	Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `alternative_text`.
`elements.buttons`	no	`array`	Displays buttons. Can contain up to 13 `button` objects.
`elements.buttons.text`	yes	`string`	Text displayed on a button.
`elements.buttons.type`	yes	`string`	Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value` (when one of them is present, the other is required). Possible values: `webview`, `message`, `url`, `phone`. More...
`elements.buttons.value`	yes	`string`	Should be used together with `elements.buttons.type` (when one of them is present, the other is required). You can use this field to give the rich message of a `webview` type (a Moment) a custom title. More...
`elements.buttons.webview_height`	yes	`string`	Required only for the `webview` button`type`. Possible values: `compact`, `full`, `tall`.
`elements.buttons.postback_id`	yes	`string`	A description of the sent action. Describes the action sent via `send_rich_message_postback`. More...
`elements.buttons.user_ids`	yes	`array`	Describes users that sent the postback with `"toggled": true`.
`elements.buttons.target`	no	`string`	Should be used for the `url` button `type`. Specifies if the URL should open in the current or a new tab. Possible values: `new`, `current`.

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.
`recipients`	always
`properties`	optionally
`template_id`	always
`elements`	optionally
`elements.title`	always
`elements.subtitle`	always
`elements.image`	always
`elements.buttons`	optionally
`elements.buttons.text`	always
`elements.buttons.type`	always
`elements.buttons.value`	always
`elements.buttons.webview_height`	always	Unless button `type` is different than `webview`.
`elements.buttons.postback_id`	always
`elements.buttons.user_ids`	always
`elements.buttons.target`	optionally

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,
				"alternative_text": "A picture of lorem ipsum"
			},
			"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": [],
					"target": "current"
				}
			]
		}
	]
}

Custom

Custom event is an event with customizable payload.

Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the event a custom ID.
`type`	yes	`string`	Event type: `custom`
`content`	no	`object`	The content you define
`recipients`	yes	`string`	Those who can receive the custom event: `all` (default) or `agents`
`properties`	no	`object`	The properties data structure

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`content`	optionally
`recipients`	always
`properties`	optionally

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the system message a custom ID.
`type`	yes	`string`	`system_message`
`text`	no	`string`	Text displayed to recipients
`system_message_type`	yes	`string`	System message type
`recipients`	no	`string`	It can be specified when sending system messages via the Send Event method. Possible values: `all`, `agents`.
`text_vars`	no	`object`	Variables used in the text

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`text`	optionally
`system_message_type`	always
`recipients`	optionally

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"
}

Field	Req./Opt.	Note
`routing_status`	optional	Returned only if the Agent's currently logged in.
`events_seen_up_to`	optional	RFC 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"
}

Field	Req./Opt.	Notes
`events_seen_up_to`	optional	RFC 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",
	"email_verified": false,
	"avatar": "example.com/avatars/1.png",
	"last_visit": {
		"started_at": "2017-10-12T15:19:21.010200Z",
		"ended_at": "2017-10-12T15:21:01.000000Z",
		"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.livechat.com/",
				"title": "LiveChat - Homepage"
			},
			{
				"opened_at": "2017-10-12T15:19:21.010200Z",
				"url": "https://www.livechat.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",
	"followed": false,
	"online": true,
	"group_ids": [
		0
	],
	"state": "browsing"
}

Field	Req./Opt.	Notes
`id`	required
`type`	required	Always equal to "customer".
`agent_last_event_created_at`	optional	RFC 3339 datetime string.
`avatar`	optional
`customer_last_event_created_at`	optional	RFC 3339 datetime string.
`created_at`	optional	RFC 3339 datetime string; the timestamp of the customer's creation.
`email`	optional
`email_verified`	optional	Specifies if the customer confirmed their email address. See Request Email Verification.
`session_fields`	optional	An array of custom object-enclosed `key:value` pairs. Expires along with the session.
`name`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string.
`last_visit`	optional
`present`	optional
`statistics`	optional
`chats`	optional
`followed`	optional	`true` if the customer is followed by the agent.
`online`	optional	`true` if the customer is logged in, `false` otherwise.
`group_ids`	optional	IDs of groups the customer is assigned to.
`state`	optional	Possible values: `browsing`, `invited`, `chatting`, `queued`, `left`.

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
		]
	}
}

Field	Req./Opt.	Note
`group_ids`	required	`group 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",
				"ended_at": "2020-05-12T11:33:33.497000Z",
				"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
}

Field	Req./Opt.	Note
`properties`	optional
`access`	optional

Chat summaries

Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread object, while Chat summary includes last_thread_summary and last_event_per_type.

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",
				"ended_at": "2020-05-12T11:33:33.497000Z",
				"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 Form event.

Sample Form fields

Copied!

{
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name"
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email"
		},
		{
			"type": "radio",
			"id": "154417206262602571",
			"label": "Chat purpose"
		},
		{
			"type": "checkbox",
			"id": "154417206262604640",
			"label": "Company industry"
		},
		{
			"type": "group_chooser",
			"id": "154417206262605324",
			"label": "Choose department"
		}
	]
}

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types

Filled 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"
			}
		}
	]
}

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types
`answer`	yes	`any`	For all field types
`answer.id`	yes	`string`	An identifier of each option a Customer can choose. For all field types.
`answer.label`	yes	`string`	Answer label; for all field types
`answer.group_id`	yes	`number`	For `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"
}

Field	Req./Opt.	Note
`access`	optional
`active`	required	Possible values: `true` (thread is still active) or `false`(thread no longer active)
`events`	optional	Doesn't exists if `restricted_access` is present.
`properties`	optional
`restricted_access`	optional	Contains the reason for access restriction.
`queue`	optional	Present only if the chat is in the queue. The wait time for an available agent is approximated in seconds.
`queues_duration`	optional	Present only in the List Archives responses if the chat was queued.
`previous_thread_id`	optional	Present only if there is a preceding thread.
`next_thread_id`	optional	Present only if there is a following thread.
`created_at`	required	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.

Methods

The API endpoint
`wss://api.livechatinc.com/v3.3/agent/rtm/ws`

Available methods


Chats	`list_chats` `list_threads` `get_chat` `list_archives` `start_chat` `resume_chat` `deactivate_chat` `follow_chat` `unfollow_chat`
Chat access	`grant_chat_access` `revoke_chat_access` `transfer_chat`
Chat users	`add_user_to_chat` `remove_user_from_chat`
Events	`send_event` `send_rich_message_postback`
Properties	`update_chat_properties` `delete_chat_properties` `update_thread_properties` `delete_thread_properties` `update_event_properties` `delete_event_properties`
Thread tags	`tag_thread` `untag_thread`
Customers	`get_customer` `list_customers` `create_customer` `update_customer` `ban_customer` `follow_customer` `unfollow_customer`
Status	`login` `change_push_notifications` `set_routing_status` `set_away_status` `logout` `list_routing_statuses`
Other	`mark_events_as_seen` `send_typing_indicator` `multicast` `list_agents_for_transfer`

GENERAL RTM API REQUEST FORMAT

Copied!

{
  "version": "<api_version>", // optional, defaults to the version of the RTM connection; versions lower than the version of the RTM connection are prohibited
  "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.


Action	`list_chats`
Required scopes *	`chats--all:ro` `chats--access:ro` `chats--my:ro`
Web API equivalent	`list_chats`
Push message	-

Parameter	Required	Type	Notes
`filters`	No	`object`	When paginating, `filters` provided in the first request are remembered and automatically used for the subsequent requests. Providing a new `filters` object will result in a `validation` error. To reset the filters, start paginating with a new set of filters.
`filters.include_active`	No	`bool`	Defines if the returned chat summary includes active chats; default: `true`.
`filters.include_chats_without_threads`	No	`bool`	Defines if the returned chat summary includes chats without any threads; default: `true`.
`filters.group_ids`	No	`array`	Array of group IDs. Max array size: 200
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`
`sort_order`	No	`string`	Possible values: `asc` - oldest chats firstm `desc` - newest chats first (default)
`limit`	No	`number`	Default: 10, maximum: 100
`page_id`	No	`string`

Field	Data type	Notes
`chats_summary`	`array`	An array of Chat summary data structures
`next_page_id`	`string`	In relation to `page_id` specified in the request. Appears in the response only when there's a next page.
`previous_page_id`	`string`	In relation to `page_id` specified in the request Appears in the response only when there's a previous page.
`found_chats`	`number`	An estimated number. The real number of found chats can slightly differ.


Action	`list_threads`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
Web API equivalent	`list_threads`
Push message	-

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`sort_order`	No	`string`	Possible values: `asc` - oldest threads first and `desc` - newest threads first (default).
`limit`	No	`number`	Default: 3, maximum: 100
`page_id`	No	`string`
`min_events_count`	No	`number`	Range: 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.
`filters`	No	`object`
`filters.from`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.to`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`


Action	`get_chat`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
Web API equivalent	`get_chat`
Push message	-

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`thread_id`	No	`string`	Default: the latest thread (if exists)


Action	`list_archives`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
Web API equivalent	`list_archives`
Push message	-

Parameter	Required	Data type	Notes
`filters`	No	`object`
`filters.query`	No	`string`
`filters.from`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.to`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.group_ids`	No	`array`	Array of group IDs. Max array size: 200
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`	* described below
`filters.agents.<filter_type>`	No	`any`	`exists` see to `false` will return unassigned chats; `true` will return the assigned ones.
`filters.tags.<filter_type>`	No	`any`
`filters.sales.<filter_type>`	No	`any`
`filters.goals.<filter_type>`	No	`any`
`filters.surveys.<survey>`	No	`array`	described below**
`filters.events.types`	No	`array`	Array of Event types. Duplicates are ignored.
`page_id`	No	`string`
`sort_order` *******	No	`string`	Default: `desc`
`limit`	No	`number`	Default: 10, min: 1, max: 100
`highlights`	No	`object`	Use it to highlight the match of `filters.query`. To enable highlights with default parameters, pass an empty object.
`highlights.pre_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `<em>`. Use it together with `highlights.post_tag`.
`highlights.post_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `</em>`. Use it together with `highlights.pre_tag`.


Action	`start_chat`
Required scopes *	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
Web API equivalent	`start_chat`
Push message	`incoming_chat`

Parameter	Required	Data type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`
`chat.access`	No	`object`
`chat.users`	No	`[]object`	The list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	User ID
`chat.users.type`	Yes	`string`	`agent` or `customer`.
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	The list of initial chat events
`chat.thread.properties`	No	`object`
`active`	No	`bool`	When set to `false`, creates an inactive thread; default: `true`.
`continuous`	No	`bool`	Starts chat as continuous (online group is not required); default: `false`.


Action	`resume_chat`
Required scopes *	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
Web API equivalent	`resume_chat`
Push message	`incoming_chat`

Parameter	Required	Type	Notes
`chat`	Yes	`object`
`chat.id`	Yes	`string`	The ID of the chat that will be resumed.
`chat.access`	No	`object`	Chat access to set, default: all agents.
`chat.properties`	No	`object`	Initial chat properties
`chat.users`	No	`[]object`	The list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	User ID
`chat.users.type`	Yes	`string`	`agent` or `customer`
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array
`chat.thread.properties`	No	`object`	Initial thread properties
`active`	No	`bool`	When set to `false`, creates an inactive thread. Default `true`.
`continuous`	No	`bool`	Sets a chat to the continuous mode. When unset, leaves the mode unchanged.

Field	Data type	Notes
`thread_id`	`string`
`event_ids`	`[]string`	Returned only when the chat was resumed with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.


Action	`deactivate_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`deactivate_chat`
Push message	`chat_deactivated`


Action	`follow_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`follow_chat`
Push message	`incoming_chat`*


Action	`unfollow_chat`
Required scopes	-
Web API equivalent	`unfollow_chat`
Push message	`chat_unfollowed`


Action	`grant_chat_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`grant_chat_access`
Push message	`chat_access_granted`

Parameter	Required	Data ype	Notes
`id`	Yes	`string`	Chat Id
`access`	Yes	`object`
`access.type`	Yes	`string`	`group`
`access.id`	Yes	any


Action	`revoke_chat_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`revoke_chat_access`
Push message	`chat_access_revoked`

RTM API Reference.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

.css-1plb8kr{color:inherit;-webkit-text-decoration:none;text-decoration:none;position:relative;}.css-1plb8kr:hover{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1plb8kr:hover:before{content:"#";position:absolute;font-weight:300;left:-1em;top:1px;opacity:0.3;}Introduction

RTM API Reference

Introduction


Action	`transfer_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`transfer_chat`
Push message	`chat_transferred`


Action	`add_user_to_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`add_user_to_chat`
Push message	`user_added_to_chat`

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible values: `agent` or `customer`
`require_active_thread`	No	`bool`	If `true`, it adds a user to a chat only if that chat has an active thread; default `false`.


Action	`remove_user_from_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`remove_user_from_chat`
Push message	`user_removed_from_chat`


Action	`send_event`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
Web API equivalent	`send_event`
Push message	`incoming_event`

Parameters	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to send the message to.
`event`	Yes	`object`	Event object
`attach_to_last_thread`	No	`bool`	The flag is ignored for active chats. For inactive chats: `true` – the event will be added to the last thread; `false` – the request will fail. Default: `false`.


Action	`send_rich_message_postback`
Required scopes	`chats.conversation--my:rw` `chats.conversation--all:rw`
Web API equivalent	`send_rich_message_postback`
Push message	`incoming_rich_message_postback`*

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`event_id`	Yes	`string`
`postback`	Yes	`object`
`postback.id`	Yes	`string`	Postback name of the button
`postback.toggled`	Yes	`bool`	Postback toggled; `true` or `false`
`thread_id`	Yes	`string`


Action	`update_chat_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
Web API equivalent	`update_chat_properties`
Push message	`chat_properties_updated`

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Id of the chat you to set a property for.
`properties`	Yes	`object`	Chat properties to set. You should stick to the general properties format and include namespace, property name and value.