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.
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.
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
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
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
, 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.2/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",
"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
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",
}'
{
"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
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"
}'
{
"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
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.
**)
<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 firstdesc
- the newest chats first
REQUEST
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"]
}
}
}'
{
"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
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 '{}'
{
"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
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"
}
}'
{
"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
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
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
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
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
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
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
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
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
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"
}
}'
{
"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
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
{
"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
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
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
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
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
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
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
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
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
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
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"
}'
{
"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 firstdesc
- 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
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 '{}'
{
"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
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"
}]
}'
{
"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.
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.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"
}]
}'
{}
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
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
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
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
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
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
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"
}'
[{
"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 methodsSee webhook payloadsErrors
{
"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!