Web API Reference

Introduction

Versioning

This document describes the Agent Chat Web API v3.2. This is the deprecated version. We encourage you to migrate to the latest stable version. Read more about versioning...

Lifecycle headers

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

What is Web API

Web API is similar to REST API. Client can send a request message that results in getting a response message. It's also possible to get webhooks.

When to use Web API

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

Web API allows for building stateless integrations. The communication is done via XHR requests. The implementation is easier than with RTM API, but you need to take possible time delays into consideration.

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

Access

The basics on authorization, access tokens, and scopes in the Agent Chat Web API.

Authorization

Agent authorization is handled with access tokens. Find out how to get an access token from Agent authorization flows. Take note you won't be able to use this token for the Customer Chat API.

Scopes

All authorization scopes are listed in the Scopes document. If a method requires certain scopes, you'll find them included in the method description. Keep in mind that Web API requires authorization every time you make a request.

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.

Postman collection

You can find all the requests from the Agent Chat Web API v3.2 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace sample tokens with your own.

Data structures

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

Methods

HTTP method	The API endpoint
`POST`	`https://api.livechatinc.com/v3.2/agent/action/<action>`

If you specify the API version in the URL, you don't have to include the optional "X-API-Version: 3.2" header.

Required Header	Value	Notes
`Content-Type`	`multipart/form-data; boundary=<boundary>`	Valid for the `upload_file` method
`Content-Type`	`application/json`	Valid for all methods except for `upload_file`
`Authorization`	`Bearer <token>`	Access token
`X-Author-Id`	`<bot_agent_id>`	Valid only for Bot Agents

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

GENERAL WEB API REQUEST FORMAT

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/<action> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    // payload
    }'

Available methods


Chats	`list_chats` `list_threads` `get_chat` `list_archives` `start_chat` `activate_chat` `deactivate_chat` `follow_chat` `unfollow_chat`
Chat access	`grant_chat_access` `revoke_chat_access` `transfer_chat`
Chat users	`add_user_to_chat` `remove_user_from_chat`
Events	`send_event` `upload_file` `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`
Status	`set_routing_status`
Other	`mark_events_as_seen` `send_typing_indicator` `multicast` `list_agents_for_transfer`

Chats

List Chats

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

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/list_chats`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
RTM API equivalent	`list_chats`
Webhook	-

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

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/list_chats \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'

Response

Copied!

{
  "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",
          "recipients": "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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/list_threads`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
RTM API equivalent	`list_threads`
Webhook	-

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.

You cannot use both limit and min_events_count at the same time.

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/list_threads \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PWJ8Y4THAV",
    }'

Response

Copied!

{
  "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",
      "recipients": "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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/get_chat`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
RTM API equivalent	`get_chat`
Webhook	-

Request

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

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/get_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PWJ8Y4THAV",
      "thread_id": "K600PKZON8"
    }'

Response

Copied!

{
  "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",
      "recipients": "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"
  }],
  "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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/list_archives`
Required scopes	`chats--all:ro` `chats--access:ro`
RTM API equivalent	`list_archives`
Webhook	-

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.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. Max array size: 200
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`	* described below
`filters.agents.<filter_type>`	No	`any`	`exists` set to `false` will return unassigned chats; `true` will return the assigned ones.
`filters.tags.<filter_type>`	No	`any`
`filters.sales.<filter_type>`	No	`any`
`filters.goals.<filter_type>`	No	`any`
`filters.surveys.<survey>`	No	`array`	described below**
`filters.events.types`	No	`array`	Array of Event types. Duplicates are ignored.
`page_id`	No	`string`
`sort_order` *******	No	`string`	Default: `desc`
`limit`	No	`number`	Default: 10, min: 1, max: 100
`highlights`	No	`object`	Use it to highlight the match of `filters.query`. To enable highlights with default parameters, pass an empty object.
`highlights.pre_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `<em>`. Use it together with `highlights.post_tag`.
`highlights.post_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `</em>`. Use it together with `highlights.pre_tag`.

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

**) <survey> contains the following fields:

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

***) sort_order can take the following values:

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

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/list_archives \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "events": {
        "types": ["message", "filled_form"]
    }
  }
}'

Response

Copied!

{
  "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"
        }
      ],
      "thread": {
        "id": "K600PKZON8",
        "active": false,
        "user_ids": [
          "smith@example.com"
        ],
        "events": [
          {
            "id": "QBT14H0Y3Y_1",
            "created_at": "2020-05-28T11:45:32.269000Z",
            "recipients": "all",
            "type": "message",
            "properties": {
              "0805e283233042b37f460ed8fbf22160": {
                "event_property": "property_value"
              }
            },
            "text": "Hello there",
            "author_id": "smith@example.com"
          }
        ],
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "thread_property": "property_value"
          }
        },
        "access": {
          "group_ids": [
            0
          ]
        },
        "created_at": "2020-05-28T11:44:58.829000Z"
      },
      "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.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/start_chat`
Required scopes *	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`start_chat`
Webhook	`incoming_chat`

*) When chat.users is defined, one of following scopes is required:

chats--all:rw
chats--access:rw
chats--my:rw

Request

Parameters	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`
`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!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/start_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

Copied!

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "PGDGHT5G"
}

Activate Chat

Restarts an archived chat.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/activate_chat`
Required scopes *	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`activate_chat`
Webhook	`incoming_chat`

*) When chat.users is defined, one of following scopes is required:

chats--all:rw
chats--access:rw
chats--my:rw

Request

Parameter	Required	Data type	Notes
`chat`	Yes	`object`
`chat.id`	Yes	`string`	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	`[]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
`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 activated with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/activate_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat": {
      "id": "PWJ8Y4THAV"
      }
    }'

Response

Copied!

{
  "thread_id": "Z8AGR5OUW"
}

Deactivate Chat

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

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/deactivate_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`deactivate_chat`
Webhook	`chat_deactivated`

Request

Parameter	Required	Data type
`chat_id`	Yes	`string`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/deactivate_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": "PJ0MRSHTDG"
    }'

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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/follow_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`follow_chat`
Webhook	-

Request

Parameter	Required	Data type
`chat_id`	Yes	`string`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/follow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PW94SJTGW6"
  }'

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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/unfollow_chat`
Required scopes	-
RTM API equivalent	`unfollow_chat`
Webhook	-

Request

Parameter	Required	Data type
`chat_id`	Yes	`string`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/unfollow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PWF6BACIKO"
   }'

Chat access

Grant Chat Access

Grants access to a new chat without overwriting the existing ones.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/grant_chat_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`grant_chat_access`
Webhook	`chat_access_granted`

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/grant_chat_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "id": "PW94SJTGW6",
  "access": {
    "type": "group",
    "id": 19
    }
  }'

Revoke Chat Access

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/revoke_chat_access`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`revoke_chat_access`
Webhook	`chat_access_revoked`

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Chat Id
`access`	Yes	`object`
`access.type`	Yes	`string`	`group` or `agent`
`access.id`	Yes	`number`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/revoke_chat_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "id": "PW94SJTGW6",
   "access": {
     "type": "group",
     "id": 19
     }
   }'

Transfer Chat

Transfers a chat to an Agent or a group. When transferring directly to an agent, the agent must have access to the transferred chat.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/transfer_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`transfer_chat`
Webhook	-

Request

Parameter	Required	Data type	Notes
`chat_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
`force`	No	`bool`	If `true`, always transfers chats. Otherwise. fails when unable to assign any Agent from the requested groups; default `false`.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/transfer_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PWF6BACIKO",
   "target": {
     "type": "group",
     "ids": [
       19
       ]
     }
   }'

Chat users

Add User to Chat

Adds a user to the chat. You can't add more than one customer user type to the chat.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/add_user_to_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`add_user_to_chat`
Webhook	`user_added_to_chat`

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/add_user_to_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PW94SJTGW6",
    "user_id": "smith@example.com",
    "user_type": "agent",
    "require_active_thread": "true"
  }'

Remove User from Chat

Removes a user from chat. Removing customer user type is not allowed. It's always possible to remove the requester from the chat.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/remove_user_from_chat`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`remove_user_from_chat`
Webhook	`user_removed_from_chat`

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible value: `agent`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/remove_user_from_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PW94SJTGW6",
    "user_id": "smith@example.com",
    "user_type": "agent"
  }'

Events

Send Event

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

It's possible to write to a chat without joining it. The user sending an event will be automatically added to the chat with the present parameter set to false (see user_added_to_chat). Sample use case: a Bot Agent that sends messages visible to all chat participants without actually joining the chat.

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 X-Author-Id header set to the bot's id.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/send_event`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`send_event`
Webhook	`incoming_event`

Request

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

Response

Field	Data type
`event_id`	`string`

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/send_event \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PW94SJTGW6",
   "event": {
     "type": "message",
     "text": "hello world",
     "recipients": "all"
     }
   }'

Response

Copied!

{
  "event_id": "K600PKZON8"
}

Upload File

Uploads a file to the server as a temporary file. It returns a URL that expires after 24 hours unless the URL is used in send_event.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/upload_file`
RTM API equivalent	-
Webhook	`incoming_event` *

*) incoming_event returns a URL that never expires.

Request

Parameter	Required	Data type	Notes
`file`	Yes	`binary`	maximum size: 10MB

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/upload_file \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: multipart/form-data; boundary=--------------------------210197025774705439685896' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F file=@/Users/MyAccount/Desktop/image.png

Response

Copied!

{
  "url": "https://cdn.livechat-files.com/api/file/lc/att/8948324/45a3581b59a7295145c3825c86ec7ab3/image.png"
}

Send Rich Message Postback

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/send_rich_message_postback`
Required scopes	`chats.conversation--my:rw` `chats.conversation--all:rw`
RTM API equivalent	`send_rich_message_postback`
Webhook	`incoming_rich_message_postback`*

*) incoming_rich_message_postback will 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/false
`thread_id`	Yes	`string`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/send_rich_message_postback \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "thread_id": "K600PKZON8",
   "event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
   "postback": {
     "id": "Method URL_yes",
     "toggled": true
     }
   }'

Properties

Update Chat Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/update_chat_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`update_chat_properties`
Webhook	`chat_properties_updated`

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you 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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q1VZR7AJCE",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat property value updated by Agent"
        }
     }
  }'

Delete Chat Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/delete_chat_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`delete_chat_properties`
Webhook	`chat_properties_deleted`

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

  curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/delete_chat_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": "Q1VZR7AJCE",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": [
        "string_property"
        ]
      }
    }'

Update Thread Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/update_thread_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`update_thread_properties`
Webhook	`thread_properties_updated`

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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.2/agent/action/update_thread_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": "Q1WZ073OA7",
    "thread_id": "Q1WZ073OB7",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "Chat thread property value updated by Agent"
        }
      }
    }'

Delete Thread Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/delete_thread_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`delete_thread_properties`
Webhook	`thread_properties_deleted`

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/delete_thread_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q1WZ073OA7",
  "thread_id": "Q1WZ073OB7",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }'

Update Event Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/update_event_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`update_event_properties`
Webhook	`event_properties_updated`

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. You should stick to the general properties format and include namespace, property name and value.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/update_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Event property value updated by Agent"
      }
    }
  }'

Delete Event Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/delete_event_properties`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`delete_event_properties`
Webhook	`event_properties_deleted`

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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/delete_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q16ZSBGX3J",
  "thread_id": "Q16ZSBGX4J",
  "event_id": "Q16ZSBGX4J_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }'

Thread tags

Tag Thread

Tags a given thread.

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

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/tag_thread`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`tag_thread`
Webhook	`thread_tagged`

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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/tag_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
   }'

Untag Thread

Untags a given thread.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/untag_thread`
Required scopes	`chats--all:rw` `chats--access:rw` `chats--my:rw`
RTM API equivalent	`untag_thread`
Webhook	`thread_untagged`

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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/untag_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
   }'

Customers

Get Customer

Returns the info about the Customer with a given customer_id.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/get_customer`
Required scopes	`customers:ro`
RTM API equivalent	`get_customer`
Push message	-

Request

Parameter	Required	Data type	Notes
`customer_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!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/get_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }'

Response

Copied!

{
  "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",
    "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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/list_customers`
Required scopes	`customers:ro`
RTM API equivalent	`list_customers`
Webhook	-

Request

All parameters are optional.

Parameter	Data type	Notes
`page_id`	`string`
`limit`	`number`	Default: 10, maximum: 100
`sort_order` *	`string`	Default: `desc`
`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`

sort_order can take the following values:

asc - oldest customers first
desc - newest customers first

**)

<string_filter_type> can take the following values :

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

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!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/list_customers \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'

Response

Copied!

{
  "customers": [
  // array of "User > Customer" objects
  ],
  "total_customers": 2340,
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Ng==" // optional
}

Create Customer

Creates a new Customer user type.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/create_customer`
Required scopes	`customers:rw`
RTM API equivalent	`create_customer`
Webhook	`customer_created`

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!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/create_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "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!

{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}

Update Customer

Updates Customer's properties.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/update_customer`
Required scopes	`customers:rw`
RTM API equivalent	`update_customer`
Webhook	-

Request

Parameter	Required	Data type	Notes
`customer_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 customer_id, which is a required parameter, you also need to include one of the optional parameters.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/update_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "customer_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!

{}

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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/ban_customer`
Required scopes	`customers.ban:rw`
RTM API equivalent	`ban_customer`
Webhook	-

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/ban_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
   "ban": {
     "days": 3
     }
   }'

Status

Set Routing Status

Changes the status of an Agent or a Bot Agent.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/set_routing_status`
Required scopes	for Agents: `agents--my:rw` `agents--all:rw`; for Bot Agents: `agents-bot--my:rw` `agents-bot--all:rw`
RTM API equivalent	`set_routing_status`
Webhook	`routing_status_set`

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.

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/set_routing_status \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "status": "accepting_chats",
    "agent_id": "smith@example.com"
  }'

Other

Mark Events as Seen

It marks an agent’s events up to a specific time as read in a customer’s chat window.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/mark_events_as_seen`
Required scopes	`chats--access:ro` `chats--all:ro`
RTM API equivalent	`mark_events_as_seen`
Webhook	`events_marked_as_seen`

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/mark_events_as_seen \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "seen_up_to": "2017-10-12T15:19:21.010200Z"
   }'

Send Typing Indicator

Specifics


Method URL	`https://api.livechatinc.com/v3.2/agent/action/send_typing_indicator`
Required scopes	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`send_typing_indicator`
Webhook	-

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat that to send the typing indicator to.
`recipients`	No	`string`	Default: `all`; `agents`
`is_typing`	Yes	`bool`

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/send_typing_indicator \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "is_typing": true
   }'

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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/multicast`
Required scopes	`multicast:rw`
RTM API equivalent	`multicast`
Webhook	-

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!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/multicast \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "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"
    }
    }
  }'

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


Method URL	`https://api.livechatinc.com/v3.2/agent/action/list_agents_for_transfer`
Required scopes	-
RTM API equivalent	`list_agents_for_transfer`
Webhook	-

Request

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

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.2/agent/action/list_agents_for_transfer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PJ0MRSHTDG"
  }'

Response

Copied!

[{
  "agent_id": "smith@example.com",
  "total_active_chats": 2
}, {
  "agent_id": "agent@example.com",
  "total_active_chats": 5
}]

Webhooks

Here's what you need to know about webhooks:

Webhooks notify you when specific events are triggered.
They can be generated by both Web and RTM API actions.
When using RTM API, you can be also notified about events with pushes.
Webhooks and pushes have similar payloads.

You can create and manage webhooks via the Configuration API.

See webhook methods See webhook payloads

Errors

Format of error payload

Copied!

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

Possible errors

Error type	Default message	Description
`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.
`entity_too_large`	Upload limit exceeded (10MB).	Client's request is too large.
`internal`	Internal server error
`license_expired`	License expired	The end of license trial or subcription.
`license_not_found`	License not found	License with the specified ID doesn't exist.
`limit_reached`	Limit reached	Resource cannot be created/modified because the change would exceed the limit
`misdirected_request`	Wrong region	Client's request should be performed to another region. The correct region is returned in the optional data object – this is where the client should be connected.
`request_timeout`	Request timed out	Timeout threshold is 15 seconds.
`too_many_requests`	Too many requests	The request's rate limit was exceeded. It'll be unblocked automatically after some time.
`unsupported_version`	Cannot call unsupported API versions.	Unsupported protocol version.
`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!