RTM API Reference

Introduction

Versioning

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

What is RTM API

Real-Time Messaging API (RTM API) is based on a websocket-like connection. Client can send a request message that results in getting a response message. It's also possible to get push messages.

When to use RTM API

If you're wondering which API to use - Agent Chat RTM API or Web API, keep on reading.

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

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

Also, the RTM API will be a better choice if you want to avoid time delays or presume significant traffic. Not what you're looking for? Perhaps, you need to use Agent Chat Web API instead.

Access

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

Authorization

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

Server pinging

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

Use one of these 2 ways of pinging the server:

Protocol message with the ping action

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

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

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

The control frame ping in the websocket protocol

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

Scopes

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

Data centers

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

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

fra: wss://api-fra.livechatinc.com/v3.5/agent/rtm/ws

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

Calling the API as a bot

It's possible to call the Agent Chat API as a bot. There are two ways to authorize the requests:

old (v3.5 and lower): a bot shares the access token with the agent who created it. You need to provide the agent token (Bearer or Basic Auth) and the X-Author-Id: <bot_id> header in the request.
new (v3.5 and higher): bots use their own authorization tokens generated with the Issue Bot Token method.

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

Specifics


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

*) chats--all:ro - to find chats from all groups.

**) chats--access:ro - to find chats from groups that the requester (related to the token) is a member of.

Request

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 first, `desc` - newest chats first (default)
`limit`	No	`number`	Default: 10, maximum: 100
`page_id`	No	`string`

filter_type can take the following values:

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

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

Response

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.

REQUEST

Copied!

{
  "action": "list_chats",
  "payload": {}
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "list_chats",
  "type": "response",
  "success": true,
  "payload": {
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
    "chats_summary": [{
      "id": "PJ0MRSHTDG",
      "last_event_per_type": {
        "message": {
          "thread_id": "K600PKZON8",
          "thread_created_at": "2020-05-07T07:11:28.288340Z",
          "event": {
            "id": "Q298LUVPRH_1",
            "created_at": "2019-12-09T12:01:18.909000Z",
            "visibility": "all",
            "type": "message",
            "text": "hello world",
            "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
          }
        },
        "system_message": {
          "thread_id": "K600PKZON8",
          "thread_created_at": "2020-05-07T07:11:28.288340Z",
          "event": {
            // "System message" event
          }
        }
      },
      "users": [{
        // "Customer" user object
      }, {
        // "Agent" user object
      }],
      "last_thread_summary": {
        "id": "K600PKZON8",
        "created_at": "2020-05-07T07:11:28.288340Z",
        "user_ids": [
          "b7eff798-f8df-4364-8059-649c35c9ed0c",
          "smith@example.com"
        ],
        "properties": {
          // "Properties" object
        },
        "active": true,
        "access": {
          "group_ids": [0]
        }
      },
      "properties": {
        // "Properties" object
      },
      "access": {
        "group_ids": [0]
      },
      "is_followed": true
    }],
    "found_chats": 4
  }
}

List Threads

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

Specifics


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

*) chats--all:ro - to find threads from all groups.

**) chats--access:ro - to find threads from groups that the requester (related to the token) is a member of.

Request

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 compatible with RFC3339 with a resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`
`filters.to`	No	`string`	Date & time format compatible with RFC3339 with a resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`

You cannot use either limit and min_events_count or filters and min_events_count at the same time.

REQUEST

Copied!

{
  "action": "list_threads",
    "payload": {
      "chat_id": "PWJ8Y4THAV"
    }
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "list_threads",
  "type": "response",
  "success": true,
  "payload": {
    "threads": [{
      "id": "K600PKZON8",
      "created_at": "2019-12-17T07:57:41.512000Z",
      "active": true,
      "user_ids": [
        "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "smith@example.com"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "visibility": "all",
        "type": "message",
        "text": "Hello",
        "author_id": "smith@example.com"
      }],
      "properties": {
        // "Property" object
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8", // optional
      "next_thread_id": "K600PKZOO8" // optional
    }],
    "found_threads": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
    "previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
  }
}

Get Chat

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

Specifics


Action	`get_chat`
Required scopes	`chats--all:ro` * or `chats--access:ro` **, depending on the requested thread’s groups.
Web API equivalent	`get_chat`
Push message	-

*) chats--all:ro - to get chat from any group.

**) chats--access:ro - to get chat from a group that the requester (related to the token) is a member of.

Request

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

REQUEST

Copied!

{
  "action": "get_chat",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8"
  }
}

Response

Copied!

{
  "request_id": "<request_id>",
  "action": "get_chat",
  "type": "response",
  "success": true,
  "payload": {
    "id": "PJ0MRSHTDG",
    "thread": {
      "id": "K600PKZON8",
      "created_at": "2020-05-07T07:11:28.288340Z",
      "active": true,
      "user_ids": [
        "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "smith@example.com"
      ],
      "events": [{
        "id": "Q20N9CKRX2_1",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "visibility": "all",
        "type": "message",
        "text": "Hello",
        "author_id": "smith@example.com"
      }],
      "properties": {
        "0805e283233042b37f460ed8fbf22160": {
          "string_property": "string_value"
        }
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8",
      "next_thread_id": "K600PKZOO8"
    },
    "users": [{
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "type": "customer",
      "present": true,
      "created_at": "2019-12-17T08:53:20.693553+01:00",
      "statistics": {
        "chats_count": 1
      },
      "agent_last_event_created_at": "2019-12-17T09:04:05.239000+01:00"
    }, {
      "id": "smith@example.com",
      "name": "Agent Smith",
      "email": "smith@example.com",
      "type": "agent",
      "present": true,
      "avatar": "https://example.com/avatar.jpg",
      "visibility": "all"
    }],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string_value"
      }
    },
    "access": {
      "group_ids": [0]
    },
    "is_followed": true
  }
}

List Archives

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

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

Specifics


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

*) chats--all:ro - to find threads from all groups.

**) chats--access:ro - to find threads from groups that the requester (related to the token) is a member of.

Request

Parameter	Required	Data type	Notes
`filters`	No	`object`
`filters.query`	No	`string`
`filters.from`	No	`string`	Date & time format compatible with RFC3339 with a resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`
`filters.to`	No	`string`	Date & time format compatible with RFC3339 with a resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`
`filters.group_ids`	No	`array`	Array of group IDs. Max array size: 200
`filters.properties.<namespace>.<name>.<properties_filter_type>`	No	`any`	* described below
`filters.agents.<filter_type>`	No	`any`	** described below `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.event_types.<event_type_filter_type>`	No	`any`	****** described below**
`filters.greetings.<greetings_filter_type>`	No	`any`	**** described below**
`filters.agent_response.<agent_response_filter_type>`	No	`any`	***** described below**
`filters.customer_countries.<filter_type>`	No	`any`	It supports country codes with the `ISO 3166-1 Alpha-2` format.
`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`.

*) <properties_filter_type> can take the following values:

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

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

**) <filter_type> can take the following values:

exists (bool)
values (type[] - an array with a specific type for property: string, int or bool)
exclude_values (type[] - an array with a specific type for property: string, int or bool)
require_every_value (bool) - if set to true, will return only those chats that have all elements passed in values or exclude_values

You can pass only one of the following values at a time: exists, values or exclude_values.

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

***) <survey> contains the following fields:

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

*****) <event_type_filter_type> can take the following values:

values (string[] - an array of Event types, duplicates are ignored)
exclude_values (string[] - an array of Event types, duplicates are ignored)
require_every_value (bool) - if set to true, will return only those chats that have all elements passed in values or exclude_values

You can pass only one of the following values at a time: values or exclude_values.

*****) sort_order can take the following values:

asc - the oldest chats first
desc - the newest chats first

******) <greetings_filter_type> can take the following values:

from (string) - Date & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
to (string) - Date & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
exists (bool)
values (int[]) - an array of greeting IDs
exclude_values (int[]) - an array of greeting IDs
groups.values (int[]) - an array of group IDs
groups.exclude_values (int[]) - an array of group IDs

******) <agent_response_filter_type> can take the following values:

exists (bool)
first (bool) - modifier that makes the other agent_response filters operate only on agents' first response
agents.values (string[]) - an array of agent IDs
agents.exclude_values (string[]) - an array of agent IDs
groups.values (int[]) - an array of group IDs
groups.exclude_values (int[]) - an array of group IDs

REQUEST

Copied!

{
  "action": "list_archives",
  "payload": {
    "filters": {
      "event_types": {
        "values": ["message", "filled_form"]
      }
    }
  }
}

Response

Copied!

{
  "request_id": "<request_id>",
  "action": "list_archives",
  "type": "response",
  "success": true,
  "payload": {
    "chats": [
      {
        "id": "PJ0MRSHTDG",
        "users": [
          {
            "id": "smith@example.com",
            "name": "Agent Smith",
            "email": "smith@example.com",
            "type": "agent",
            "present": true,
            "avatar": "https://cdn.livechat-files.com/api/file/avatar.png",
            "visibility": "all"
          }
        ],
        "thread": {
          "id": "K600PKZON8",
          "active": false,
          "user_ids": [
            "smith@example.com"
          ],
          "events": [ //optional
            {
              "id": "QBT14H0Y3Y_1",
              "created_at": "2020-05-28T11:45:32.269000Z",
              "visibility": "all",
              "type": "message",
              "properties": {
                "0805e283233042b37f460ed8fbf22160": {
                  "event_property": "property_value"
                }
              },
              "text": "Hello, how can I help you?",
              "author_id": "smith@example.com"
            }
          ],
          "properties": {
            "0805e283233042b37f460ed8fbf22160": {
              "thread_property": "property_value"
            }
          },
          "access": {
            "group_ids": [
              0
            ]
          },
          "created_at": "2020-05-28T11:44:58.829000Z",
          "previous_thread_id": "K600PKZOM8", // optional
          "next_thread_id": "K600PKZOO8", // optional
          "previous_accessible_thread_id": "K600PKZOM8", // optional
          "next_accessible_thread_id": "K600PKZOO8" // optional
        },
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "chat_property": "property_value"
          }
        },
        "access": {
          "group_ids": [
            0
          ]
        },
        "is_followed": false
      }
    ],
    "found_chats": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "previous_page_id": "MTUxNzM5ODEzMTQ5Ng=="
  }
}

Start Chat

Starts a chat.

Authors (except the requester) of all initial events must be listed in the users field. The default visibility of both the events and users is set to all and cannot be changed. The method updates the requester's events_seen_up_to as if they've seen all chat events.

Specifics


Action	`start_chat`
Required scopes	`chats--all:rw` * or `chats--access:rw` **, depending on the requested groups
Web API equivalent	`start_chat`
Push message	`incoming_chat`

*) chats--all:rw - to start a chat in any group.

**) chats--access:rw - to start a chat in groups that the requester (related to the token) is a member of.

Request

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

Response

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.

REQUEST

Copied!

{
  "action": "start_chat",
  "payload": {}
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "start_chat",
  "type": "response",
  "success": true,
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "PGDGHT5G"
  }
}

Resume Chat

Restarts an archived chat.

Specifics


Action	`resume_chat`
Required scopes	`chats--all:rw` * or `chats--access:rw` **, depending on the requested groups
Web API equivalent	`resume_chat`
Push message	`incoming_chat`

*) chats--all:rw - to resume a chat in any group.

**) chats--access:rw - to resume a chat in groups that the requester (related to the token) is a member of.

Request

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.

Response

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.

REQUEST

Copied!

{
  "action": "resume_chat",
  "payload": {
  "chat": {
    "id": "PWJ8Y4THAV"
  }
  }
}

Response

Copied!

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

Deactivate Chat

Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible.

The requester must be present on the list of chat users. You can override it by setting the ignore_requester_presence parameter.

Specifics


Action	`deactivate_chat`
Required scopes	`chats--all:rw` * or `chats--access:rw` **, depending on the requested groups
Web API equivalent	`deactivate_chat`
Push message	`chat_deactivated`

*) chats--all:rw - to deactivate a chat in any group.

**) chats--access:rw - to deactivate a chat in groups that the agent (related to the token) is a member of.

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

REQUEST

Copied!

{
  "action": "deactivate_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}

Response

Copied!

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

Follow Chat

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

Specifics


Action	`follow_chat`
Required scopes	`chats--all:ro` * or `chats--access:ro` **, depending on the requested groups
Web API equivalent	`follow_chat`
Push message	`incoming_chat`*******

*) chats--all:ro - to follow chats from all groups.

**) chats--access:ro - to follow chats from groups that the requester (related to the token) is a member of.

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

Request

Parameter	Required	Data type
`id`	Yes	`string`

REQUEST

Copied!

{
  "action": "follow_chat",
  "payload": {
    "id": "PW94SJTGW6"
  }
}

Response

Copied!

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

Unfollow Chat

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

Specifics


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

Request

Parameter	Required	Data type
`id`	Yes	`string`

REQUEST

Copied!

{
  "action": "unfollow_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}

Response

Copied!

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

Chat access

Transfer Chat

Transfers a chat to an agent or a group. The following restrictions apply:

The transferred chat must be active.
The requester must be present on the list of chat users.
- You can override it by setting the ignore_requester_presence parameter.
When transferring directly to an agent, the agent must have access to the transferred chat.

Specifics


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

*) chats--all:rw - to transfer a chat taking place in any group.

**) chats--access:rw - to transfer a chat taking place in groups that the requester (related to the token) is a member of. (The requester groups and the current groups of the chat must overlap - at least one group must be in common.)

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Chat ID
`target`	No	`object`	If missing, the chat will be transferred within the current group.
`target.type`	Yes	`string`	`group` or `agent`
`target.ids`	Yes	`array`	`group` or `agent` IDs array
`ignore_agents_availability`	No	`bool`	If `true`, allows the chat to be enqueued after the transfer. Otherwise, fails when unable to immediately assign any agent from the requested groups; default `false`.
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

REQUEST

Copied!

{
  "action": "transfer_chat",
  "payload": {
    "id": "PJ0MRSHTDG",
    "target": {
      "type": "group",
      "ids": [19]
    }
  }
}

Response

Copied!

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

Chat users

Add User to Chat

Adds a user to the chat. The following restrictions apply:

The chat must be active.
The requester must be present on the list of chat users.
- You can override it by setting the ignore_requester_presence parameter.
You can't have more than one customer in the chat.
Additional agents must also have access to the chat.
customer must be added with visibility:all.

To learn how to add more than one agent to the chat, reach out to us on Discord or via email, developers@text.com.

To add a bot to a chat in a group it’s not part of, use the author_id property set to the bot’s id. Read more...

Specifics


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

* chats--all:rw - to add the requester (related to the token) to a chat taking place in any group.

**) chats--access:rw - to add a user to a chat taking place in groups that the user is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible values: `agent` or `customer`
`visibility`	Yes	`string`	Possible values: `all` or `agents`
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

REQUEST

Copied!

{
  "action": "add_user_to_chat",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "user_id": "smith@example.com",
    "user_type": "agent",
    "visibility": "all"
  }
}

Response

Copied!

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

Remove User from Chat

Removes a user from chat. The following restrictions apply:

You can't remove the customer.
The requester must be present on the list of chat users.
- You can override it by setting the ignore_requester_presence parameter.

Specifics


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

*) chats--all:rw - to remove a user from a chat taking place in any group.

**) chats--access:rw - to remove a user from a chat taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible value: `agent`
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

REQUEST

Copied!

{
  "action": "remove_user_from_chat",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "user_id": "smith@example.com",
  "user_type": "agent"
  }
}

Response

Copied!

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

Events

Send Event

Sends an Event object. Use this method to send a message by specifying the Message event type in the request.

The user must be added to the chat before they can send an event. Events with visibility:agents are sent to agents only, and with visibility:all to all users. Users with visibility:agents cannot send events with visibility:all.

The method updates the requester's events_seen_up_to as if they've seen all chat events.

To call the API as a bot, use the author_id property set to the bot's id in the payload. Read more...

Specifics


Action	`send_event`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`send_event`
Push message	`incoming_event`

*) chats--all:rw - to send an event to a chat taking place in any group.

**) chats--access:rw - to send an event to a chat taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.

REQUEST

Copied!

{
  "action": "send_event",
  "payload": {
  "chat_id": "PW94SJTGW6",
    "event": {
      "type": "message",
      "text": "hello world",
      "visibility": "all"
    }
  }
}

Response

Copied!

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

Send Rich Message Postback

Specifics


Action	`send_rich_message_postback`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`send_rich_message_postback`
Push message	`incoming_rich_message_postback`*******

*) chats--all:rw - to send a postback to a chat taking place in any group.

**) chats--access:rw - to send a postback to a chat taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

***) incoming_rich_message_postback - to be sent only for active threads.

Request

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`

REQUEST

Copied!

{
  "action": "send_rich_message_postback",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
  "postback": {
    "id": "Method URL_yes",
    "toggled": true
  }
  }
}

Response

Copied!

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

Properties

Update Chat Properties

Specifics


Action	`update_chat_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`update_chat_properties`
Push message	`chat_properties_updated`

*) chats--all:rw - to update properties in a chat taking place in any group.

**) chats--access:rw - to update properties in a chat taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.

REQUEST

Copied!

{
  "action": "update_chat_properties",
  "payload": {
    "id": "Q1VZR7AJCE",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "Chat property value updated by Agent"
      }
    }
  }
}

Response

Copied!

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

Delete Chat Properties

Specifics


Action	`delete_chat_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`delete_chat_properties`
Push message	`chat_properties_deleted`

*) chats--all:rw - to delete properties in a chat taking place in any group.

**) chats--access:rw - to delete properties in a chat taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.

REQUEST

Copied!

{
  "action": "delete_chat_properties",
  "payload": {
    "id": "Q1VZR7AJCE",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": [
        "string_property"
      ]
    }
  }
}

Response

Copied!

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

Update Thread Properties

Specifics


Action	`update_thread_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`update_thread_properties`
Push message	`thread_properties_updated`

*) chats--all:rw - to update properties in a thread taking place in any group.

**) chats--access:rw - to update properties in a thread taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.

REQUEST

Copied!

{
  "action": "update_thread_properties",
  "payload": {
  "chat_id": "Q1WZ073OA7",
  "thread_id": "Q1WZ073OB7",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat thread property value updated by Agent"
      }
    }
  }
}

Response

Copied!

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

Delete Thread Properties

Specifics


Action	`delete_thread_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`delete_thread_properties`
Push message	`thread_properties_deleted`

*) chats--all:rw - to delete properties in a thread taking place in any group.

**) chats--access:rw - to delete properties in a thread taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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

REQUEST

Copied!

{
  "action": "delete_thread_properties",
  "payload": {
   "chat_id": "Q1WZ073OA7",
   "thread_id": "Q1WZ073OB7",
   "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}

Response

Copied!

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

Update Event Properties

Specifics


Action	`update_event_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`update_event_properties`
Push message	`event_properties_updated`

*) chats--all:rw - to update properties in an event taking place in any group.

**) chats--access:rw - to update properties in an event taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.
`event_id`	Yes	`string`	Id of the event you want to set properties for.
`properties`	Yes	`object`	Chat properties to set.

REQUEST

Copied!

{
  "action": "update_event_properties",
  "payload": {
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Event property value updated by Agent"
      }
    }
  }
}

Response

Copied!

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

Delete Event Properties

Specifics


Action	`delete_event_properties`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`delete_event_properties`
Push message	`event_properties_deleted`

*) chats--all:rw - to delete properties in an event taking place in any group.

**) chats--access:rw - to delete properties in an event taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

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.
`event_id`	Yes	`string`	Id of the event you want to delete the properties of.
`properties`	Yes	`object`	Event properties to delete. You should stick to the general properties format and include namespace, property name and value.

REQUEST

Copied!

{
  "action": "delete_event_properties",
  "payload": {
  "chat_id": "Q16ZSBGX3J",
  "thread_id": "Q16ZSBGX4J",
  "event_id": "Q16ZSBGX4J_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }
}

Response

Copied!

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

Thread tags

Tag Thread

Tags a given thread.

Read how to list all available tags and create a new tag.

Specifics


Action	`tag_thread`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`tag_thread`
Push message	`thread_tagged`

*) chats--all:rw - to tag a thread taking place in any group.

**) chats--access:rw - to tag a thread taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to add a tag to.
`thread_id`	Yes	`string`	Id of the thread you want to add a tag to.
`tag`	Yes	`string`	Tag name. It's case sensitive.

REQUEST

Copied!

{
  "action": "tag_thread",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
  }
}

Response

Copied!

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

Untag Thread

Untags a given thread.

Specifics


Action	`untag_thread`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`untag_thread`
Push message	`thread_untagged`

*) chats--all:rw - to untag a thread taking place in any group.

**) chats--access:rw - to untag a thread taking place in groups that the requester (related to the token) is a member of. (The agent groups and the chat groups must overlap - at least one group must be in common.)

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to remove a tag from.
`thread_id`	Yes	`string`	Id of the thread you want to remove a tag from.
`tag`	Yes	`string`	Tag name. It's case sensitive.

REQUEST

Copied!

{
  "action": "untag_thread",
  "payload": {
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
  }
}

Response

Copied!

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

Customers

Get Customer

Returns the info about the Customer with a given id.

Specifics


Action	`get_customer`
Required scopes	`customers:ro`
Web API equivalent	`get_customer`
Push message	-

Request

Parameter	Required	Data type	Notes
`id`	Yes	string

Response

Field	Data type	Notes
`id`	string	Customer's ID.
`type`	string	`customer`
`name`	string	Customer's name. Returned only if set.
`email`	string	Customer's email. Returned only if set.
`avatar`	string	Customer's avatar. Returned only if set.
`created_at`	string	Specifies when the customer's identity was created.
`session_fields`	[]object	An array of custom object-enclosed `key:value` pairs. Returned only if set. Available for the session duration.
`statistics`	object	Counters for started threads, opened pages, etc.
`last_visit`	object	Geolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once.
`chat_ids`	[]string	IDs of a customer's chats. Returned only if the customer had at least one chat.

REQUEST

Copied!

{
  "action": "get_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "get_customer",
  "type": "response",
  "success": true,
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "type": "customer",
    "created_at": "2017-10-11T15:19:21.010200Z",
    "name": "Thomas Anderson",
    "email": "t.anderson@example.com",
    "avatar": "example.com/avatars/1.jpg",
    "session_fields": [{
      "custom_key": "custom_value"
    }, {
      "another_custom_key": "another_custom_value"
    }],
    "last_visit": {
      "started_at": "2017-10-12T15:19:21.010200Z",
      "ended_at": "2017-10-12T15:20:22.010200Z",
      "referrer": "http://www.google.com/",
      "ip": "<customer_ip>",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
      "geolocation": {
        "latitude": "-14.6973803",
        "longitude": "-75.1266898",
        "country": "Poland",
        "country_code": "PL",
        "region": "Dolnoslaskie",
        "city": "Wroclaw",
        "timezone": "Europe/Warsaw"
      },
      "last_pages": [{
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.livechat.com/",
        "title": "LiveChat - Homepage"
      }, {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.livechat.com/tour",
        "title": "LiveChat - Tour"
      }]
    },
    "statistics": {
      "chats_count": 3,
      "threads_count": 9,
      "visits_count": 5,
      "page_views_count": 1337,
      "greetings_shown_count": 69,
      "greetings_accepted_count": 42
    },
    "__priv_lc2_customer_id": "test_771305.dafea66e5c", // old customer_id
    "agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
    "customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
    "chat_ids": [
      "PWJ8Y4THAV"
    ]
  }
}

List Customers

It returns the list of Customers.

Specifics


Action	`list_customers`
Required scopes	`customers:ro`
Web API equivalent	`list_customers`
Push message	-

Request

All parameters are optional.

Parameter	Data type	Notes
`page_id`	`string`
`limit`	`number`	Default: 10, maximum: 100
`sort_order` *	`string`	Default: `desc`
`sort_by` **	`string`	Default: `created_at`
`filters`	`object`
`filters.country.<string_filter_type>` *******	`object`
`filters.email.<string_filter_type>` *******	`object`
`filters.name.<string_filter_type>` *******	`object`
`filters.customer_id.<string_filter_type>` *******	`object`
`filters.chats_count.<range_filter_type>` ********	`object`
`filters.threads_count.<range_filter_type>` ********	`object`
`filters.visits_count.<range_filter_type>` ********	`object`
`filters.created_at.<date_range_filter_type>`*****	`object`
`filters.agent_last_event_created_at.<date_range_filter_type>` *****	`object`
`filters.customer_last_event_created_at.<date_range_filter_type>` *****	`object`
`filters.chat_group_ids.<integer_filter_type>` *******	`object`	Maximum 40 group ids at once
`filters.include_customers_without_chats`	`bool`

sort_order can take the following values:

asc
desc

**)

sort_by can take the following values:

created_at
threads_count
visits_count
agent_last_event
customer_last_event

When sorting by fields other than created_at, the entries with identical values will be additionally sorted by their creation time.

***)

<string_filter_type> can take the following values :

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

<integer_filter_type> can take the following values:

values (int[] - an array of integers)
exclude_values (int[] - an array of integers)

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

****)

<range_filter_type> can take the following values:

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

*****)

<date_range_filter_type> can take the following values:

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

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

Response

Field	Data type	Notes
`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.

REQUEST

Copied!

{
  "action": "list_customers",
  "payload": {}
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "list_customers",
  "type": "response",
  "success": true,
  "payload": {
  "customers": [
    // an array of "User > Customer" objects
  ],
  "total_customers": 2340,
  "limited_customers": 120, // optional
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Ng==" // optional
  }
}

Create Customer

Creates a new Customer user type.

Specifics


Action	`create_customer`
Required scopes	`customers:rw`
Web API equivalent	`create_customer`
Push message	`incoming_customer`

Request

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.

REQUEST

Copied!

{
  "action": "create_customer",
  "payload": {
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "https://example.com/avatars/1.png",
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }]
  }
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "create_customer",
  "type": "response",
  "success": true,
  "payload": {
   "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

Update Customer

Updates Customer's properties.

Specifics


Action	`update_customer`
Required scopes	`customers:rw`
Web API equivalent	`update_customer`
Push message	`customer_updated`

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`	UUID v4 format is required.
`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.

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

When updating customer data while the customer has an active chat, the update will take effect after the chat has ended.

REQUEST

Copied!

{
  "action": "update_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "name": "Thomas Anderson",
    "email": "t.anderson@example.com",
    "avatar": "https://example.com/avatars/1.png",
    "session_fields": [{
      "custom_key": "custom_value"
    }, {
      "another_custom_key": "another_custom_value"
    }]
  }
}

Response

Copied!

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

Ban Customer

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

Specifics


Action	`ban_customer`
Required scopes	`customers.ban:rw`
Web API equivalent	`ban_customer`
Push message	`customer_banned`

Request

Parameter	Required	Data type
`id`	Yes	`string`
`ban`	Yes	`object`
`ban.days`	Yes	`number`

REQUEST

Copied!

{
  "action": "ban_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "ban": {
      "days": 3
    }
  }
}

Response

Copied!

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

Follow Customer

Marks a customer as followed. As a result, the requester (an agent) will receive the info about all the changes related to that customer via pushes. Once the customer leaves the website or is unfollowed, the agent will no longer receive that information.

Following a customer causes the agent to receive customer-related pushes as long as the followed customer is available. The followed customer may be transferred to a group the agent doesn't have access to, which makes the customer unavailable to the agent. At that moment, the agent stops receiving pushes related to that customer. When the customer is transferred back and becomes available again, the pushes resume.

Agents don't need to follow the customers they're chatting with in order to receive related pushes. Agents will be receiving pushes related to those customers as long as the chats last.

Specifics


Action	`follow_customer`
Required scopes	`customers:ro`
Web API equivalent	`follow_customer`
Push message	`incoming_customer`*

*) It won't be sent when the requester already follows the customer or is chatting with that customer.

Request

Parameter	Required	Data type
`id`	Yes	`string`

REQUEST

Copied!

{
  "action": "follow_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

Response

Copied!

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

Unfollow Customer

Removes the agent from the list of customer's followers. Calling this method on a customer the agent's chatting with will result in success, however, the agent will still receive pushes about the customer's data updates. The unfollowing will take effect once the chat ends.

Specifics


Action	`unfollow_customer`
Required scopes	-
Web API equivalent	`unfollow_customer`
Push message	`customer_unfollowed`

Request

Parameter	Required	Data type
`id`	Yes	`string`

REQUEST

Copied!

{
  "action": "unfollow_customer",
  "payload": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

Response

Copied!

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

Status

Login

It returns the initial state of the current Agent.

Specifics


Action	`login`
Required scopes	`chats--access:ro` * and `customers:ro` and `multicast:ro` *** and `agents--all:ro`**** and `agents-bot--all:ro` ***
Web API equivalent	-
Push message	-

*) chats--access:ro - to get pushes about chats from the requester groups.

**) customers:ro - to get pushes about customers.

***) multicast:ro - to get pushes about multicast.

****) agents--all:ro - to get pushes about agent updates.

*****) agents-bot--all:ro - to get pushes about bot updates.

Request

Parameter	Required	Data type	Notes
`token`	Yes	`string`	OAuth token from the Agent's account
`timezone`	No	`string`
`reconnect`	No	`bool`	Reconnecting sets the status to the last known state instead of the default one.
`application`	No	`object`
`application.name`	No	`string`	Application name
`application.version`	No	`string`	Application version
`away` *	No	`bool`	When `true`, the connection is set to the `away` state. Defaults to `false`.
`customer_monitoring_level`	No	`string`	Possible values: `my`, `chatting`, `invited`, `online`, `highest_available` **. Defaults to `my` if login creates the first session; otherwise it preserves the current `customer_monitoring_level`.
`pushes`	No	`object`	Use case: when you want to receive only specific pushes. By default, it's set to `all` for the version of your currently established RTM connection.
`pushes.<version>`	Yes	`[]string`	A list of push subscriptions for a specific version;`<version>` is a version number, without `v` prefix. Possible values: push names.

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

** These values mean:

my - only the customers from chats the agent is assigned to
chatting - all customers that are chatting within the groups the agent is assigned to
invited - all customers that are invited to chat within the groups the agent is assigned to
online - all customers visiting the website assigned to the agent’s groups
highest_available - sets customer monitoring level to the highest available level based on license configuration. More information about the license configuration is available by contacting support

Response

Field	Data type	Notes
`access`	`object`
`properties`	`object`

REQUEST

Copied!

{
  "action": "login",
  "payload": {
    "token": "Bearer dal:test_1fgTbfXmgthj4cZSA",
    "pushes": {
      "3.5": ["incoming_chat", "incoming_multicast"],
      "3.6": ["all"]
    }
  }
}

Response

Copied!

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

Set Away Status

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

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

Specifics


Action	`set_away_status`
Required scopes	`agents--my:rw`
Web API equivalent	-
Push message	-

Request

Parameter	Required	Data type
`away`	Yes	`bool`

REQUEST

Copied!

{
  "action": "set_away_status",
  "payload": {
  "away": true
  }
}

Response

Copied!

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

Set Routing Status

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

Specifics


Action	`set_routing_status`
Required scopes	for Agents: `agents--my:rw` * or `agents--all:rw` ; for Bot Agents: `agents-bot--my:rw` *** or `agents-bot--all:rw` ******
Web API equivalent	`set_routing_status`
Push message	`routing_status_set`

*) agents--my:rw - to set my routing status.

**) agents--all:rw - to set the routing status of any agent within a license.

***) agents-bot--my:rw - to set the routing status of bots that belong to the client_id related to the token (within a license).

****) agents-bot--all:rw - to set the routing status of any bots within a license.

Request

Parameter	Required	Data type	Notes
`status`	Yes	`string`	For Agents: `accepting_chats` or `not_accepting_chats`; for Bot Agents: `accepting_chats`, `not_accepting_chats`, or `offline`
`agent_id`	No	`string`	If not specified, the requester's status will be updated.

REQUEST

Copied!

{
  "action": "set_routing_status",
  "payload": {
  "status": "accepting_chats",
  "agent_id": "smith@example.com"
  }
}

Response

Copied!

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

Logout

Logs the Agent out.

Specifics


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

REQUEST

Copied!

{
  "action": "logout",
  "payload": {}
}

Response

Copied!

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

List Routing Statuses

Returns the current routing status of each agent selected by the provided filters.

Specifics


Action	`list_routing_statuses`
Required scopes	`agents--all:ro` * and `agents-bot--all:ro` **
Web API equivalent	`list_routing_statuses`
Push message	-

*) agents--all:ro - to list statuses of agents.

**) agents-bot--all:ro - to list statuses of bots.

Request

Parameter	Required	Type	Notes
`filters`	No	`object`
`filters.group_ids`	No	`array`

REQUEST

Copied!

{
  "action": "list_routing_statuses",
  "payload": {
    "filters": {
      "group_ids": [
        0
      ]
    }
  }
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "list_routing_statuses",
  "type": "response",
  "success": true,
  "payload": [{
    "agent_id": "smith@example.com",
    "status": "accepting_chats"
  }, {
    "agent_id": "agent@example.com",
    "status": "not_accepting_chats"
  }]
}

Other

Mark Events as Seen

Specifics


Action	`mark_events_as_seen`
Required scopes	`chats--all:ro` * or `chats--access:ro` **
Web API equivalent	`mark_events_as_seen`
Push message	`events_marked_as_seen`

*) chats--all:ro - to mark events as seen in a chat taking place in any group.

**) chats--access:ro - to mark events as seen in a chat taking place in groups that the requester (related to the token) is a member of (the agent groups and the chat groups must intersect - at least one group must be common).

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`seen_up_to`	Yes	`string`	RFC 3339 date-time format

REQUEST

Copied!

{
  "action": "mark_events_as_seen",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "seen_up_to": "2017-10-12T15:19:21.010200Z"
  }
}

Response

Copied!

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

Send Typing Indicator

Specifics


Action	`send_typing_indicator`
Required scopes	`chats--all:rw` * or `chats--access:rw` **
Web API equivalent	`send_typing_indicator`
Push message	-

*) chats--all:rw - to send the typing indicator to a chat taking place in any group.

**) chats--access:rw - to send the typing indicator to a chat taking place in groups that the requester (related to the token) is a member of (the agent groups and the chat groups must intersect - at least one group must be common).

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to send the typing indicator to.
`visibility`	No	`string`	`all` (default), `agents`
`is_typing`	Yes	`bool`

REQUEST

Copied!

{
  "action": "send_typing_indicator",
  "payload": {
  "chat_id": "PJ0MRSHTDG",
  "is_typing": true
  }
}

Response

Copied!

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

Multicast

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

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

Specifics


Action	`multicast`
Required scopes	`multicast:rw`
Web API equivalent	`multicast`
Push message	`incoming_multicast`

Request

Parameter	Required	Data type	Notes
`recipients`	Yes	`object`	*
`content`	Yes	`any`	A JSON message to be sent
`type`	No	`string`	Multicast message type

*) recipients can take the following values:

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

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

REQUEST

Copied!

{
  "action": "multicast",
  "payload": {
  "recipients": {
    "agents": {
    "all": true,
    "ids": [
      "smith@example.com",
      "agent@example.com"
    ],
    "groups": [
      1,
      2
    ]
    },
    "customers": {
    "ids": [
      "b7eff798-f8df-4364-8059-649c35c9ed0c"
    ]
    }
  },
  "content": {
    "example": {
    "nested": "json"
    }
  }
  }
}

Response

Copied!

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

List Agents For Transfer

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

The method only returns Agents with statuses online and not accepting chats. Offline Agents aren't returned.
Only chats with Customers are taken into account in total_active_chats.

Specifics


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

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	The ID of the chat you want to transfer

REQUEST

Copied!

{
  "action": "list_agents_for_transfer",
  "payload": {
   "chat_id": "PJ0MRSHTDG"
  }
}

Response

Copied!

{
  "request_id": "<request_id>", // optional
  "action": "list_agents_for_transfer",
  "type": "response",
  "success": true,
  "payload": [{
  "agent_id": "smith@example.com",
  "active_chats": 2
  }, {
  "agent_id": "agent@example.com",
  "active_chats": 5
  }]
}

Pushes

Here's what you need to know about pushes:

They are generated primarily by RTM API actions, but also by Web API actions.
They notify you when specific events occur.
Can be delivered only in the websocket transport.
You don't need to register pushes to receive them.
Their equivalents in Web API are webhooks. Pushes and webhooks have similar payloads.
There are no retries for pushes. To determine if a user has seen an event, compare the event's created_at parameter with the user's events_seen_up_to field.

See available pushes

general push format

Copied!

{
  "version": "<api_version>",
  "request_id": "<request_id>", // optional, applies only to the requester
  "action": "<action>",
  "type": "push",
  "payload": {
  // optional payload
  }
}

Errors

Format of error payload

Copied!

{
  "error": {
    "type": "misdirected_request",
    "message": "Wrong region",
    "data": {
      // optional
      "region": "dal"
    }
  }
}

Possible errors

Error type	Default message	Description
`agent_offline`	Agent offline	The server couldn't process the request because the agent was offline.
`authentication`	Authentication error	An invalid or expired access token.
`authorization`	Authorization error	User is not allowed to perform the action.
`chat_inactive`	Chat is inactive	An action that requires an active thread performed on a chat with no active threads.
`internal`	Internal server error
`license_expired`	License expired	The end of license trial or subcription.
`missing_access`	Missing access	The requester doesn't have access to a given resource.
`not_found`	Not found	The requested resource wasn't found.
`pending_requests_limit_reached`	Requests limit reached	The limit of pending requests within one websocket connection has been reached. The limit is 10.
`requester_already_offline`	Requester is already offline	The method is only allowed for the logged in Agents (via RTM API).
`requester_awaiting_approval`	Requester awaiting approval	A new Agent hasn't been approved by the license owner yet.
`request_timeout`	Request timed out	Timeout threshold is 15 seconds.
`requester_suspended`	Requester suspended	The rights of a given Agent have been withdrawn by the license owner.
`seats_limit_exceeded`	Seats limit exceeded	Displayed on the attempt of logging in. All seats within a given license are already taken.
`service_unavailable`	Service unavailable	New requests are temporarily not being accepted.
`too_many_requests`	Too many requests	The request's rate limit was exceeded. It'll be unblocked automatically after some time.
`validation`	Wrong format of request
`wrong_product_version`	Wrong product version	License is not LiveChat 3 (probably still LiveChat 2).

Contact us

If you found a bug or a typo, you can let us know directly on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@text.com. We'll be happy to hear from you!