RTM API Reference

Introduction

Versioning

This documentation describes the Agent Chat Real-Time Messaging API v3.3, which is a legacy versions. For production-ready applications, it's best to use to the current stable version. Read more about versioning...

Lifecycle headers

When opening a WebSocket connection, the API responses will contain one of two headers related to the API lifecycle: Legacy or Deprecation. These headers specify when the associated stage ends (in the YYYY-MM-DD format).

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

Data structures

To find sample payloads of events, users, and other common structures such as chats or threads visit the Data structures document.

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 object. Does not support the `form` type event in the LiveChat app.
`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`.

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.


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`

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 type	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`


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`

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

RTM API Reference

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. Does not support the `form` type event in the LiveChat app.
`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.


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

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Id of the chat you want to delete property for.
`properties`	Yes	`object`	Chat properties to delete.