RTM API Reference

Introduction

Versioning

This documentation describes the Agent Chat Real-Time Messaging API v3.1. This is the legacy version. We encourage you to migrate to the latest stable version. 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.1/agent/rtm/ws

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

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

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

Sample File in response

Copied!

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "file",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "recipients": "all",
  "properties": {
    // "Properties" object
  },
  "name": "image25.png", // generated server-side
  "url": "https://example.com/image25.png",
  "thumbnail_url": "https://example.com/thumbnail.png", // generated server-side
  "thumbnail2x_url": "https://example.com/thumbnail2x.png", // generated server-side
  "content_type": "image/png", // generated server-side
  "size": 123444, // generated server-side
  "width": 640, // generated server-side
  "height": 480 // generated server-side
}

Filled form

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

Request

Parameter	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	An array of filled form fields

Sample Filled form in response

Copied!

{
    "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
    "custom_id": "31-0C-1C-07-DB-16",
    "type": "filled_form",
    "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
    "created_at": "2017-10-12T15:19:21.010200Z",  // generated server-side
    "recipients": "all",
    "properties": {
        // "Properties" object
    },
    "form_id": "1473433500211",
    "fields": [{
        "type": "name",
        "id": "154417206262603539",
        "label": "Your name",
        "answer": "John Doe"
    }, {
        "type": "email",
        "id": "154417206262601584",
        "label": "Your email",
        "answer": "customer1@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": {
            "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", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "recipients": "all",
  "properties": {
    // "Properties" object
  }
}

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`.
`elements.buttons`	no	`array`	Displays buttons. Can contain up to 11 `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`. Possible values: `webview`, `message`, `url`, `phone`. More...
`elements.buttons.value`	yes	`string`	Should be used together with `elements.buttons.type`.
`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`.

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

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": {
    // "Properties" object
  },
  "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

The 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 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": {
    // "Properties" object
  }
}

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": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@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": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@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"
}

Customer

Sample Customer data structure

Copied!

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "example.com/avatars/1.png",
  "last_visit": {
    "started_at": "2017-10-12T15:19:21.010200Z",
    "referrer": "http://www.google.com/",
    "ip": "<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"
      }
    ]
  },
  "fields": {
    "custom field name": "custom field value"
  },
  "statistics": {
    "chats_count": 3,
    "threads_count": 9,
    "visits_count": 5
  },
  "__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",
  "created_at": "2017-10-11T15:19:21.010200Z",
  "present": true, // optional, applies only to customer located in chat object
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}

Field	Req./Opt.	Note
`agent_last_event_created_at`	optional
`avatar`	optional
`customer_last_event_created_at`	optional
`created_at`	optional
`email`	optional
`fields`	optional	Isn't present when the chat is archived.
`name`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string
`last_visit`	optional
`present`	optional
`statistics`	optional

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",
  "users": [
    // array of "User" objects
  ],
  "threads": [
    // optional
    // "Thread" object
  ],
  "threads_summary": [
    {
      "thread_id": "K600PKZON8",
      "order": 129846129847
    },
    {
      "thread_id": "K600PKZON8",
      "order": 129846129848
    }
  ],
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "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",
  "users": [
    // array of "User" objects
  ],
  "last_event_per_type": {
    // last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_order": 3,
      "event": {
        // "restricted_access": true
        // or
        // "Event > Message" object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON6",
      "thread_order": 1,
      "event": {
        // "restricted_access": true
        // or
        // "Event > System message" object
      }
    }
    // ...
  },
  "last_thread_summary": {
    "id": "K600PKZON8",
    "order": 3,
    "timestamp": 1473433500,
    "user_ids": ["agent1@example.com"],
    "properites": {
      // "Properites" object
    },
    "tags": ["bug_report"]
  },
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": false
}

Filled form fields

A component of the Filled form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `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`	Answer id; for all field types
`answer.label`	yes	`string`	Answer label; for all field types
`answer.group_id`	yes	`number`	For `group_chooser`

Response

Copied!

{
    "fields": [{
        "type": "name",
        "id": "154417206262603539",
        "label": "Your name",
        "answer": "John Doe"
    }, {
        "type": "email",
        "id": "154417206262601584",
        "label": "Your email",
        "answer": "customer1@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": {
            "group_id": 1,
            "label": "Marketing"
        }
    }]
}

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": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure

Copied!

{
  "id": "K600PKZON8",
  "timestamp": 1473433500,
  "active": true,
  "user_ids": ["agent1@example.com"],
  "restricted_access": true,
  "events": [
    // array of "Event" objects
  ],
  "order": 112057129857,
  "properties": {
    // "Properties" object
  },
  "access": {
    // "Access" object
  }
}

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 `true`.
`properties`	optional	-
`restricted_access`	optional	-

Methods

In the websocket transport, actions generate pushes. RTM API actions can also trigger webhooks, but they need to be registered first.

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

Available methods


Chats	`get_chats_summary` `get_chat_threads_summary` `get_chat_threads` `get_archives` `start_chat` `activate_chat` `close_thread` `follow_chat` `unfollow_chat`
Chat access	`grant_access` `revoke_access` `set_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_chat_thread_properties` `delete_chat_thread_properties` `update_event_properties` `delete_event_properties`
Thread tags	`tag_chat_thread` `untag_chat_thread`
Customers	`get_customers` `create_customer` `update_customer` `ban_customer`
Status	`login` `change_push_notifications` `update_agent` `set_away_status` `logout`
Other	`mark_events_as_seen` `send_typing_indicator` `multicast`

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

Get Chats Summary

It returns summaries of the chats an Agent has access to.


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

Parameter	Required	Type	Notes
`filters`	No	`object`	Mustn't change between requests for subsequent pages. Otherwise, the behavior is undefined.
`filters.include_active`	No	`bool`	Defines if the returned chat summary includes active chats; default: `true`.
`filters.group_ids`	No	`array`	Array of group IDs.
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`
`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
`found_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.
`previous_page_id`	`string`	In relation to `page_id` specified in the request.


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

Parameter	Required	Data ype	Notes
`chat_id`	Yes	`string`
`order`	No	`string`	Possible values: `asc` - oldest chats first, `desc` - newest chats first (default)
`limit`	No	`number`	Defaul: 10, maximum: 100
`page_id`	No	`string`

Field	Data type	Notes
`found_threads`	`number`	The number of threads in a chat
`next_page_id`	`string`	In relation to `page_id` specified in the request.
`previous_page_id`	`string`	In relation to `page_id` specified in the request.


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


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

Parameter	Required	Data type	Notes
`filters`	No	`object`
`filters.query`	No	`string`
`filters.date_from`	No	`string`	`YYYY-MM-DD` format
`filters.date_to`	No	`string`	`YYYY-MM-DD` format
`filters.agent_ids`	No	`array`	Array of agent IDs
`filters.thread_ids`	No	`array`	Array of thread IDs. Cannot be used with other filters or pagination; max array size: 20.
`filters.group_ids`	No	`array`	Array of group IDs
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`	* described below
`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**
`pagination`	No	`object`
`pagination.page`	No	`number`	Default: 1, min: 1, max: 1000
`pagination.limit`	No	`number`	Default: 25, min: 0, max: 100


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

Parameter	Required	Data type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`
`chat.access`	No	`object`
`chat.users`	No	`array`	The list of existing users. Only one user is allowed (type `customer`).
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	The list of initial chat events
`chat.thread.properties`	No	`object`
`continuous`	No	`bool`	Starts chat as continuous (online group is not required); default: `false`.

Field	Data type	Notes
`chat_id`	`string`
`thread_id`	`string`
`event_ids`	`[]string`	Returned 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.


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

Parameter	Required	Type	Notes
`chat`	Yes	`object`
`chat.id`	Yes	`string`	The ID of the chat that will be activated.
`chat.access`	No	`object`	Chat access to set, default: all agents.
`chat.properties`	No	`object`	Initial chat properties
`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
`chat.thread.properties`	No	`object`	Initial chat thread properties
`continuous`	No	`bool`	Sets a chat to the continuous mode. When unset, leaves the mode unchanged.


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


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


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


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

Parameter	Required	Data ype	Notes
`resource`	Yes	`string`	`chat` or `customer`
`id`	Yes	`string`	Resource Id
`access`	Yes	`object`	The entity that is granted access to the specified resource
`access.type`	Yes	`string`	`group`
`access.id`	Yes	`number`


Action	`revoke_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`revoke_access`
Push message	`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	`set_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
Web API equivalent	`set_access`
Push message	`access_set`


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

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible values: `agent` or `customer`


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


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`