RTM API Reference

Introduction

Versioning

This document describes the Customer Chat Real-Time Messaging API v3.4. 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 - Customer Chat RTM API or Web API, keep on reading.

Real-Time Messaging API allows for building stateful integrations that require logging in and maintaining the connection. Since connection maintenance is required, the implementation might be more challenging than with Web API.

Customer Chat RTM API enables communication in real time. It supports pushes like sneak peek, typing indicator, and other. Web API doesn’t have equivalent webhooks, which means you won't be informed about certain events using Web API.

Also, the RTM API will be a better choice if you want to avoid time delays or presume significant traffic.

Not what you're looking for? Perhaps, you need to use Customer Chat Web API instead.

Access

The basics on authorization and server pinging in the Customer Chat RTM API.

Authorization

Customer authorization is handled with access tokens. Find out how to get an access token from Customer authorization flow. You need to authorize within 30 seconds from establishing the connection. Otherwise, the connection will be closed. Given that the connection is continuosly maintained, you only need to authorize once.

Server pinging

After successful authorization, the client needs to ping the server every 15 seconds. Otherwise, the connection will be closed after about 30 seconds of inactivity. Until authorization is completed, ping is a no-op.

Use one of these 2 ways of pinging the server:

Protocol message with the ping action

For web applications and backend integrations (e.g. in Python, Go). Send the following request every 15 seconds:

{
  "action": "ping",
  "payload": {}
}

After pinging the server, the client will receive a response with the ping action. Thanks to that, the client can make sure the connection is still alive.

The control frame ping in the websocket protocol

For backend integrations; unavailable in web browsers. Read more about the control frame ping.

Data centers

LiveChat system operates in two data centers: dal (USA) and fra (Europe). The default data center is dal.

For backend applications, you can specify the region in the request header. The mechanism is the same as in Customer Chat Web API reference. It doesn't work for frontend applications, though. Instead, frontend apps connect to a region different than the default one by specifying the region suffix in the URL.

fra: wss://api-fra.livechatinc.com/v3.4/customer/rtm/ws

dal: wss://api.livechatinc.com/v3.4/customer/rtm/ws

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.4/customer/rtm/ws`

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

Required parameter	Data type
`organization_id`	`string`

Available methods


Chats	`list_chats` `list_threads` `get_chat` `start_chat` `resume_chat` `deactivate_chat`
Events	`send_event` `send_rich_message_postback` `send_sneak_peek`
Properties	`update_chat_properties` `delete_chat_properties` `update_thread_properties` `delete_thread_properties` `update_event_properties` `delete_event_properties`
Customers	`update_customer` `update_customer_page` `set_customer_session_fields` `get_customer`
Status	`login` `list_group_statuses`
Other	`get_form` `get_predicted_agent` `get_url_info` `mark_events_as_seen` `accept_greeting` `cancel_greeting`

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

GENERAL RTM API RESPONSE FORMAT

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "type": "response",
  "success": true,
  "payload": {
  // optional
  }
}

Chats

List Chats

It returns summaries of the chats a Customer participated in.


Action	`list_chats`
Web API equivalent	`list_chats`
Push message	-

Parameter	Required	Type	Notes
`limit`	No	`number`	Default: 10, maximum: 25
`sort_order`	No	`string`	Possible values: `asc`, `desc` (default). Chat summaries are sorted by the creation date of its last thread.
`page_id`	No	`string`

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


Action	`list_threads`
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.


Action	`get_chat`
Web API equivalent	`get_chat`
Push message	-

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


Action	`start_chat`
Web API equivalent	`start_chat`
Push message	`incoming_chat`

Parameter	Required	Data type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`	Initial chat properties
`chat.access`	No	`object`	Chat access to set, default: all agents.
`chat.users`	No	`array`	List of existing users. Only one user is allowed (type `customer`).
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array. Does not support the `form` type event in the LiveChat app.
`chat.thread.properties`	No	`object`	Initial thread properties
`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`
Web API equivalent	`resume_chat`
Push message	`incoming_chat`

Parameter	Required	Data type	Notes
`name`	No	`string`
`email`	No	`string`
`avatar`	No	`string`	URL of the Customer's avatar.
`session_fields`	No	`[]object`	An array of custom object-enclosed `key:value` pairs. Respects the order of items.

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.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`
Web API equivalent	`deactivate_chat`
Push message	`incoming_event` and `chat_deactivated`


Action	`send_event`
Web API equivalent	`send_event`
Push message	`incoming_event`

Parameter	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`
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	`send_sneak_peek`
Web API equivalent	`send_sneak_peek`
Push message	-

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat to send a sneak peek to.
`sneak_peek_text`	Yes	`string`	Sneak peek text


Action	`update_chat_properties`
Web API equivalent	`update_chat_properties`
Push message	`chat_properties_updated`

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

RTM API Reference

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`
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 properties of.
`properties`	Yes	`object`	Chat properties to delete.


Action	`update_thread_properties`
Web API equivalent	`update_thread_properties`
Push message	`thread_properties_updated`

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


Action	`delete_thread_properties`
Web API equivalent	`delete_thread_properties`
Push message	`thread_properties_deleted`

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to delete the properties of.
`thread_id`	Yes	`string`	Id of the thread you want to delete the properties of.
`properties`	Yes	`object`	Thread properties to delete.


Action	`update_event_properties`
Web API equivalent	`update_event_properties`
Push message	`event_properties_updated`


Action	`delete_event_properties`
Web API equivalent	`delete_event_properties`
Push message	`event_properties_deleted`


Action	`update_customer`
Web API equivalent	`update_customer`
Push message	`customer_updated`