Web API Reference
Introduction
Versioning
This document describes the Agent Chat Web API v3.4, which is a legacy version. For production-ready applications, it's best to use to the current 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.
Data centers
LiveChat system operates in two data centers: dal
(USA) and fra
(Europe). The default data center is dal
.
All the LiveChat OAuth 2.1 access tokens have a prefix: dal:
or fra:
. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix>
optional header.
Summing up, if the user token starts with fra
, you should add the X-Region: fra
header. If the token starts with dal
, you don’t have to specify the header.
If you get the misdirected_request
error, use the prefix returned in the error as the value of X-Region
.
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
Sometimes, you want to send an event as a bot. To do it, you need to have a token that allows you to send it. The token can be easily generated for an agent, but you cannot generate a token for a bot. The other time you want to add a user to your chat, and this user happens to be a bot in the group with no access to this chat, so you cannot add it.
In both situations, the X-Author-Id
header is what you need to include in your request. With it, you can authorize using the agent’s token and send the event as a bot or add a bot to a chat even if the bot belongs to the group that has no access to this chat.
X-Author-Id: <bot_id>
header is needed with a Bearer Token that needs to have the same client_id
as the bot or PAT that is from the organization that owns the bot's client_id
.
Postman collection
You can find all the requests from the Agent Chat Web API v3.4 in Postman. In our collection, we use environment variables that store, for example, the access token. Importing the collection from the link below downloads the 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.4/agent/action/<action> |
If you specify the API version in the URL, you don't have to include the optional "X-API-Version: 3.4"
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_id> | Valid only for Bot Agents |
GENERAL WEB API REQUEST FORMAT
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/<action> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
// payload
}'
Available methods
Chats
List Chats
It returns summaries of the chats an Agent has access to.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/list_chats |
Required scopes | chats--all:ro * or chats--access:ro ** |
RTM API equivalent | list_chats |
Webhook | - |
*) 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.
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
, orbool
) - exclude_values (type[] - array with specific type for property:
string
,int
, orbool
)
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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_chats \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'
{
"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
Method URL | https://api.livechatinc.com/v3.4/agent/action/list_threads |
Required scopes | chats--all:ro * or chats--access:ro ** |
RTM API equivalent | list_threads |
Webhook | - |
*) 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_threads \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWJ8Y4THAV"
}'
{
"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
Method URL | https://api.livechatinc.com/v3.4/agent/action/get_chat |
Required scopes | chats--all:ro * or chats--access:ro **, depending on the requested thread’s groups. |
RTM API equivalent | get_chat |
Webhook | - |
*) 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/get_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWJ8Y4THAV",
"thread_id": "K600PKZON8"
}'
{
"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
Method URL | https://api.livechatinc.com/v3.4/agent/action/list_archives |
Required scopes | chats--all:ro * or chats--access:ro ** |
RTM API equivalent | list_archives |
Webhook | - |
*) 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.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>.<properties_filter_type> | No | any | * described below |
filters.agents.<filter_type> | No | any | ** described below 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.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 |
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
orbool
)exclude_values
(type[]
- an array with a specific type for property:string
,int
orbool
)
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
orbool
)exclude_values
(type[]
- an array with a specific type for property:string
,int
orbool
)require_every_value
(bool
) - if set totrue
, will return only those chats that have all elements passed invalues
orexclude_values
You can pass only one of the following values at a time: exists
, values
or exclude_values
.
***)
<survey>
contains the following fields:
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
) - if set totrue
, will return only surveys withsurvey_id
type
(string
) - allowed values:pre_chat
,post_chat
values
(string[]
) - an array of answer_idsexclude_values
(string[]
) - an array of answer_idsgroups.values
(int[]
) - an array of group IDsgroups.exclude_values
(int[]
) - an array of group IDs
****)
<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 totrue
, will return only those chats that have all elements passed invalues
orexclude_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 firstdesc
- 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 IDsexclude_values
(int[]
) - an array of greeting IDsgroups.values
(int[]
) - an array of group IDsgroups.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 otheragent_response
filters operate only on agents' first responseagents.values
(string[]
) - an array of agent IDsagents.exclude_values
(string[]
) - an array of agent IDsgroups.values
(int[]
) - an array of group IDsgroups.exclude_values
(int[]
) - an array of group IDs
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_archives \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"filters": {
"event_types": {
"values": ["message", "filled_form"]
}
}
}'
{
"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 there",
"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
Method URL | https://api.livechatinc.com/v3.4/agent/action/start_chat |
Required scopes | chats--all:rw * or chats--access:rw **, depending on the requested groups |
RTM API equivalent | start_chat |
Webhook | 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
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 | |
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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/start_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "PGDGHT5G"
}
Resume Chat
Restarts an archived 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
Method URL | https://api.livechatinc.com/v3.4/agent/action/resume_chat |
Required scopes | chats--all:rw * or chats--access:rw **, depending on the requested groups |
RTM API equivalent | resume_chat |
Webhook | 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 | Data type | Notes |
---|---|---|---|
chat | Yes | object | |
chat.id | Yes | string | 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/resume_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat": {
"id": "PWJ8Y4THAV"
}
}'
{
"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
Method URL | https://api.livechatinc.com/v3.4/agent/action/deactivate_chat |
Required scopes | chats--all:rw * or chats--access:rw **, depending on the requested groups |
RTM API equivalent | deactivate_chat |
Webhook | 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 . |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/deactivate_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"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.4/agent/action/follow_chat |
Required scopes | chats--all:ro * or chats--access:ro **, depending on the requested groups |
RTM API equivalent | follow_chat |
Webhook | - |
*) 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.
Request
Parameter | Required | Data type | |
---|---|---|---|
id | Yes | string |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/follow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"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.4/agent/action/unfollow_chat |
Required scopes | - |
RTM API equivalent | unfollow_chat |
Webhook | - |
Request
Parameter | Required | Data type | |
---|---|---|---|
id | Yes | string |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/unfollow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"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.
- You can override it by setting the
- When transferring directly to an agent, the agent must have access to the transferred chat.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/transfer_chat |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | transfer_chat |
Webhook | 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 . |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/transfer_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "PJ0MRSHTDG",
"target": {
"type": "group",
"ids": [
19
]
}
}'
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 override it by setting the
- You can't have more than one
customer
in the chat. - Additional agents must also have access to the chat.
customer
must be added withvisibility: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 X-Author-Id
header set to the bot’s id. Read more...
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/add_user_to_chat |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | add_user_to_chat |
Webhook | 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 . |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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",
"visibility": "all",
"ignore_requester_presence": true
}'
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.
- You can override it by setting the
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/remove_user_from_chat |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | remove_user_from_chat |
Webhook | 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 . |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.
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 X-Author-Id
header set to the bot's id. Read more...
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/send_event |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | send_event |
Webhook | 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
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. Default: false . For inactive chats: true – the event will be added to the last thread; false – the request will fail. The only event type that can be sent to inactive chats is a system message. |
Response
Field | Data type |
---|---|
event_id | string |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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",
"visibility": "all"
}
}'
{
"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.4/agent/action/upload_file |
Required scopes | - |
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
curl -X POST \
https://api.livechatinc.com/v3.4/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
{
"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.4/agent/action/send_rich_message_postback |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | send_rich_message_postback |
Webhook | 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/false |
thread_id | Yes | string |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/update_chat_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | update_chat_properties |
Webhook | 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 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "Q1VZR7AJCE",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "Chat property value updated by Agent"
}
}
}'
Delete Chat Properties
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/delete_chat_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | delete_chat_properties |
Webhook | 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 of. |
properties | Yes | object | Chat properties to delete. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/delete_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "Q1VZR7AJCE",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
}'
Update Thread Properties
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/update_thread_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | update_thread_properties |
Webhook | 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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/delete_thread_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | delete_thread_properties |
Webhook | 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 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
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/update_event_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | update_event_properties |
Webhook | 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. You should stick to the general properties format and include namespace, property name and value. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/delete_event_properties |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | delete_event_properties |
Webhook | 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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/tag_thread |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | tag_thread |
Webhook | 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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/untag_thread |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | untag_thread |
Webhook | 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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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 id
.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/get_customer |
Required scopes | customers:ro |
RTM 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/get_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}'
{
"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
Method URL | https://api.livechatinc.com/v3.4/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 |
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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_customers \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
{
"customers": [
// 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
Method URL | https://api.livechatinc.com/v3.4/agent/action/create_customer |
Required scopes | customers:rw |
RTM API equivalent | create_customer |
Webhook | 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
curl -X POST \
https://api.livechatinc.com/v3.4/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"
}]
}'
{
"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
Update Customer
Updates Customer's properties.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/update_customer |
Required scopes | customers:rw |
RTM API equivalent | update_customer |
Webhook | customer_session_fields_updated * |
* The webhook will be sent only if the customer has active chats.
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.
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/update_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"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"
}]
}'
{}
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.4/agent/action/ban_customer |
Required scopes | customers.ban:rw |
RTM API equivalent | ban_customer |
Webhook | - |
Request
Parameter | Required | Data type | |
---|---|---|---|
id | Yes | string | |
ban | Yes | object | |
ban.days | Yes | number |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/ban_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"ban": {
"days": 3
}
}'
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
Method URL | https://api.livechatinc.com/v3.4/agent/action/follow_customer |
Required scopes | customers:ro |
RTM API equivalent | follow_customer |
Webhook | - |
Request
Parameter | Required | Data type | |
---|---|---|---|
id | Yes | string |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/follow_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}'
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
Method URL | https://api.livechatinc.com/v3.4/agent/action/unfollow_customer |
Required scopes | - |
RTM API equivalent | unfollow_customer |
Webhook | - |
Request
Parameter | Required | Data type | |
---|---|---|---|
id | Yes | string |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/unfollow_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}'
Status
Set Routing Status
Changes the status of an Agent or a Bot Agent.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/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 **** |
RTM API equivalent | set_routing_status |
Webhook | 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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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"
}'
List Routing Statuses
Returns the current routing status of each agent selected by the provided filters.
Specifics
Method URL | https://api.livechatinc.com/v3.4/agent/action/list_routing_statuses |
Required scopes | agents--all:ro * and agents-bot--all:ro ** |
RTM API equivalent | list_routing_statuses |
Webhook | - |
*) 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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_routing_statuses \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"filters": {
"group_ids": [
0
]
}
}'
[{
"agent_id": "smith@example.com",
"status": "accepting_chats"
}, {
"agent_id": "agent@example.com",
"status": "not_accepting_chats"
}]
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.4/agent/action/mark_events_as_seen |
Required scopes | chats--all:ro * or chats--access:ro ** |
RTM API equivalent | mark_events_as_seen |
Webhook | 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 |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/agent/action/send_typing_indicator |
Required scopes | chats--all:rw * or chats--access:rw ** |
RTM API equivalent | send_typing_indicator |
Webhook | - |
*) 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 that to send the typing indicator to. |
visibility | No | string | Default: all ; agents |
is_typing | Yes | bool |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/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
curl -X POST \
https://api.livechatinc.com/v3.4/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.4/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
curl -X POST \
https://api.livechatinc.com/v3.4/agent/action/list_agents_for_transfer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PJ0MRSHTDG"
}'
[{
"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.
- There's a limit of three weebhoks for every action a Client ID can register.
You can create and manage webhooks via the Configuration API.
See webhook methodsSee webhook payloadsErrors
{
"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. |
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. |
missing_access | Missing access | The requester doesn't have access to a given resource. |
not_found | Not found | The requested resource wasn't found. |
request_timeout | Request timed out | Timeout threshold is 15 seconds. |
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. |
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!