Web API Reference
Introduction
Versioning
This document describes the Agent Chat Web API v3.1. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...
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 OAuth2.0 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.
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.1 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 the sample token with your own.
Events
One of the data structures are events. They are sent to a chat via the send_event method.
Apart from events, there are also Properties, Users, and Other common data structures.
These are the available event types:
File
The File event informs about an uploaded file.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | |
type | yes | string | file |
recipients | yes | string | Possible values: all (default), agents |
properties | no | object | Properties |
url | yes | string | Has to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file. |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string. |
type | always | |
author_id | always | |
recipients | always | |
properties | optionally | |
name | always | |
url | always | |
thumbnail_url, thumbnail2x_url | only for images | |
content_type | always | |
size, width, height | only for images |
Sample File in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "file",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"recipients": "all",
"properties": {},
"name": "image25.png",
"url": "https://example.com/image25.png",
"thumbnail_url": "https://example.com/thumbnail.png",
"thumbnail2x_url": "https://example.com/thumbnail2x.png",
"content_type": "image/png",
"size": 123444,
"width": 640,
"height": 480
}Filled form
The Filled form event contains data from a form (prechat or postchat survey).
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | |
type | yes | string | filled_form |
recipients | yes | string | Possible values: all (default), agents |
properties | no | object | Properties |
form_id | yes | string | |
fields | yes | array | The fields a form contains. See filled form fields for details. |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string. |
type | always | |
author_id | always | |
recipients | always | |
properties | optionally | |
form_id | always | |
fields | always | An array of filled form fields |
Sample Filled form in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "filled_form",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"recipients": "all",
"properties": {},
"form_id": "1473433500211",
"fields": [
{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "John Doe"
},
{
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "customer1@example.com"
},
{
"type": "radio",
"id": "154417206262602571",
"label": "Chat purpose",
"answer": {
"id": "0",
"label": "Support"
}
},
{
"type": "checkbox",
"id": "154417206262604640",
"label": "Company industry",
"answers": [
{
"id": "0",
"label": "automotive"
},
{
"id": "1",
"label": "it"
}
]
},
{
"type": "group_chooser",
"id": "154417206262605324",
"label": "Choose department",
"answer": {
"group_id": 1,
"label": "Marketing"
}
}
]
}Message
The Message event contains text message to other chat users.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | |
text | yes | string | Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages. |
type | yes | string | message |
recipients | yes | string | Possible values: all (default), agents |
properties | no | object | Properties |
postback | no | object | Indicates that the message event was generated in response to a rich message event. |
postback.id | yes | string | ID of the postback from the rich message event. |
postback.thread_id | yes | string | ID of the thread with the rich message event. |
postback.event_id | yes | string | ID of the rich message event. |
postback.type | no | string | Should be used together with postback.value (when one of them is present, the other is required). |
postback.value | no | string | Should be used together with postback.type (when one of them is present, the other is required). |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | |
custom_id | optionally | |
created_at | always | Date & time format with a resolution of microseconds, UTC string. |
type | always | message |
author_id | always | |
recipients | always | |
text | always | |
postback | optionally | Appears in a message only when triggered by a rich message. |
postback.id | always | |
postback.thread_id | always | |
postback.event_id | always | |
postback.type | optionally | Appears only if postback.value is present. |
postback.value | optionally | Appears only if postback.type is present. |
properties | optionally | Properties |
Sample Message in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "message",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"text": "hello there",
"postback": {
"id": "action_call",
"thread_id": "K600PKZON8",
"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
"type": "phone",
"value": "790034890"
},
"recipients": "all",
"properties": {}
}Rich message
Rich message (RM) event contains a rich message data structure. Read more about rich messages.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | You can give your RM a custom ID. |
type | yes | string | Event type: rich_message |
recipients | yes | string | Those who can display the rich message: all (default) or agents |
properties | no | object | The properties data structure |
template_id | yes | string | Defines how every Rich Message will be presented. Values: cards, sticker, or quick_replies. |
elements | no | array | Can contain up to 10 element objects. |
elements.title | yes | string | Displays formatted text on RMs. |
elements.subtitle | yes | string | Displays formatted text on RMs. |
elements.image | yes | image | Displays images on RMs. Required param: url; Optional params: name, content_type, size, width, height. |
elements.buttons | no | array | Displays buttons. Can contain up to 11 button objects. |
elements.buttons.text | yes | string | Text displayed on a button. |
elements.buttons.type | yes | string | Defines the behavior after a user clicks the button. Should be used together with elements.buttons.value. Possible values: webview, message, url, phone. More... |
elements.buttons.value | yes | string | Should be used together with elements.buttons.type. |
elements.buttons.webview_height | yes | string | Required only for the webview buttontype. Possible values: compact, full, tall. |
elements.buttons.postback_id | yes | string | A description of the sent action. Describes the action sent via send_rich_message_postback. More... |
elements.buttons.user_ids | yes | array | Describes users that sent the postback with "toggled": true. |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
author_id | always | Generated server-side |
created_at | always | Date & time format with a resolution of microseconds, UTC string. Generated server-side. |
recipients | always | |
properties | optionally | |
template_id | always | |
elements | optionally | |
elements.title | always | |
elements.subtitle | always | |
elements.image | always | |
elements.buttons | optionally | |
elements.buttons.text | always | |
elements.buttons.type | always | |
elements.buttons.value | always | |
elements.buttons.webview_height | always | Unless button type is different than webview. |
elements.buttons.postback_id | always | |
elements.buttons.user_ids | always |
Sample Rich message in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "rich_message",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"recipients": "all",
"properties": {},
"template_id": "cards",
"elements": [
{
"title": "Lorem ipsum dolor.",
"subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"image": {
"name": "image25.png",
"url": "https://example.com/image25.png",
"content_type": "image/png",
"size": 123444,
"width": 640,
"height": 480
},
"buttons": [
{
"text": "yes",
"postback_id": "action_yes",
"user_ids": [
"b7eff798-f8df-4364-8059-649c35c9ed0c"
]
},
{
"text": "no",
"postback_id": "action_no",
"user_ids": []
},
{
"type": "phone",
"text": "value",
"value": "790034890",
"webview_height": "tall",
"postback_id": "action_call",
"user_ids": []
}
]
}
]
}Custom
Custom event is an event with customizable payload.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | You can give the event a custom ID. |
type | yes | string | Event type: custom |
content | no | object | The content you define |
recipients | yes | string | Those who can receive the custom event: all (default) or agents |
properties | no | object | The properties data structure |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
author_id | always | Generated server-side |
created_at | always | Date & time format with a resolution of microseconds, UTC string; generated server-side |
content | optionally | |
recipients | always | |
properties | optionally |
Sample Custom in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "custom",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2017-10-12T15:19:21.010200Z",
"content": {
"custom": {
"nested": "json"
}
},
"recipients": "all",
"properties": {}
}System message
System message event is native system event sent in specific situations.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | You can give the system message a custom ID. |
type | yes | string | system_message |
text | no | string | Text displayed to recipients |
system_message_type | yes | string | System message type |
recipients | no | string | It can be specified when sending system messages via the Send Event method. Possible values: all, agents. |
text_vars | no | object | Variables used in the text |
Response
| Field | Returned | Notes |
|---|---|---|
id | always | Generated server-side |
custom_id | optionally | |
type | always | |
created_at | always | Date & time format with a resolution of microseconds, UTC string; generated server-side |
text | optionally | |
system_message_type | always | |
recipients | optionally |
Sample System message in response
Copied!
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"type": "system_message",
"created_at": "2017-10-12T15:19:21.010200Z",
"text": "Hello there!",
"system_message_type": "routing.assigned",
"text_vars": {
"agent": "John Doe"
}
}Users
Users are another important data structure. Within this data structure type, we can distinguish:
Agent
Sample Agent data structure
Copied!
{
"id": "agent1@example.com",
"type": "agent",
"name": "Support Team",
"email": "agent1@example.com",
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"routing_status": "accepting_chats"
}
| Field | Req./Opt. | Note |
|---|---|---|
routing_status | optional | Returned only if the Agent is currently logged in. |
My profile
Sample My profile data structure
Copied!
{
"id": "agent1@example.com",
"type": "agent",
"name": "Support Team",
"email": "agent1@example.com",
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"routing_status": "accepting_chats",
"permission": "administrator"
}
Customer
Sample Customer data structure
Copied!
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"name": "John Smith",
"email": "customer1@example.com",
"avatar": "example.com/avatars/1.png",
"last_visit": {
"started_at": "2017-10-12T15:19:21.010200Z",
"referrer": "http://www.google.com/",
"ip": "<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": {
"country": "Poland",
"country_code": "PL",
"region": "Dolnoslaskie",
"city": "Wroclaw",
"timezone": "Europe/Warsaw"
},
"last_pages": [
{
"opened_at": "2017-10-12T15:19:21.010200Z",
"url": "https://www.livechat.com/",
"title": "LiveChat - Homepage"
},
{
"opened_at": "2017-10-12T15:19:21.010200Z",
"url": "https://www.livechat.com/tour",
"title": "LiveChat - Tour"
}
]
},
"fields": {
"custom field name": "custom field value"
},
"statistics": {
"chats_count": 3,
"threads_count": 9,
"visits_count": 5
},
"__priv_lc2_customer_id": "test_771305.dafea66e5c", //old customer_id
"agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
"customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
"created_at": "2017-10-11T15:19:21.010200Z",
"present": true, // optional, applies only to customer located in chat object
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
| Field | Req./Opt. | Notes |
|---|---|---|
agent_last_event_created_at | optional | |
avatar | optional | |
customer_last_event_created_at | optional | |
created_at | optional | |
email | optional | |
fields | optional | Is not present when the chat is archived. |
name | optional | |
events_seen_up_to | optional | RFC 3339 datetime string |
last_visit | optional | |
present | optional | |
statistics | optional |
Other common structures
Apart from Events and Users, there are also other common data structures you might work with. Those are:
Access
Sample Access data structure
Copied!
{
"access": {
"group_ids": [1, 2]
}
}
| Field | Req./Opt. | Note |
|---|---|---|
group_ids | required | group 0 means that all agents can see it. |
Chats
Sample Chat data structure
Copied!
{
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"threads": [
// optional
// "Thread" object
],
"threads_summary": [
{
"thread_id": "K600PKZON8",
"order": 129846129847
},
{
"thread_id": "K600PKZON8",
"order": 129846129848
}
],
"properites": {
// "Properites" object
},
"access": {
// "Access" object
},
"is_followed": true
}
| Field | Req./Opt. | |
|---|---|---|
properties | optional | |
access | optional |
Chat summaries
Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread object, while Chat summary includes last_thread_summary and last_event_per_type.
Sample Chat summary data structure
Copied!
{
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"last_event_per_type": {
// last event of each type in chat
"message": {
"thread_id": "K600PKZON8",
"thread_order": 3,
"event": {
// "restricted_access": true
// or
// "Event > Message" object
}
},
"system_message": {
"thread_id": "K600PKZON6",
"thread_order": 1,
"event": {
// "restricted_access": true
// or
// "Event > System message" object
}
}
// ...
},
"last_thread_summary": {
"id": "K600PKZON8",
"order": 3,
"timestamp": 1473433500,
"user_ids": ["agent1@example.com"],
"properites": {
// "Properites" object
},
"tags": ["bug_report"]
},
"properites": {
// "Properites" object
},
"access": {
// "Access" object
},
"is_followed": false
}
Filled form fields
A component of the Filled form event.
| Field | Required | Data type | Notes |
|---|---|---|---|
fields | yes | array of objects | The fields a form contains. |
type | yes | string | Possible values: checkbox, email, name, question, textarea, group_chooser, radio, select |
id | yes | string | Field id, for all field types |
label | yes | string | Field label; for all field types |
answer | yes | any | For all field types |
answer.id | yes | string | Answer id; for all field types |
answer.label | yes | string | Answer label; for all field types |
answer.group_id | yes | number | For group_chooser |
Response
Copied!
{
"fields": [{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "John Doe"
}, {
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "customer1@example.com"
}, {
"type": "radio",
"id": "154417206262602571",
"label": "Chat purpose",
"answer": {
"id": "0",
"label": "Support"
}
}, {
"type": "checkbox",
"id": "154417206262604640",
"label": "Company industry",
"answers": [{
"id": "0"
"label": "automotive"
}, {
"id": "1"
"label": "it"
}]
}, {
"type": "group_chooser",
"id": "154417206262605324",
"label": "Choose department",
"answer": {
"group_id": 1,
"label": "Marketing"
}
}]
}
Properties
Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.
Sample Properties data structure
Copied!
{
"properties": {
"rating": {
// <property_namespace>
"score": {
// <property_name>
"value": 1 // <property_value>
},
"comment": {
"value": "rated good!"
}
},
"routing": {
"idle": {
"value": false
}
}
}
}
Threads
Sample Thread data structure
Copied!
{
"id": "K600PKZON8",
"timestamp": 1473433500,
"active": true,
"user_ids": ["agent1@example.com"],
"restricted_access": true,
"events": [
// array of "Event" objects
],
"order": 112057129857,
"properties": {
// "Properties" object
},
"access": {
// "Access" object
}
}
| Field | Req./Opt. | Note |
|---|---|---|
access | optional | - |
active | required | Possible values: true (thread is still active) or false(thread no longer active) |
events | optional | Doesn't exists if restricted_access is true. |
properties | optional | - |
restricted_access | optional | - |
Methods
Web API actions can generate webhooks, as well as pushes. However, pushes can be delivered only in the websocket transport. If you want to be notified about emitted events with webhooks, you need to register them first.
| HTTP method | The API endpoint |
|---|---|
POST | https://api.livechatinc.com/v3.1/agent/action/<action> |
| 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-Region | fra | Required for a license from Europe. More info... |
X-Author-Id | <bot_agent_id> | Valid only for Bot Agents |
X-API-Version | API version, for example 3.1 | You don't need this header if you specify API version in the URL. |
GENERAL WEB API REQUEST FORMAT Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/<action> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
// payload
}'
Available methods
Chats
Get Chats Summary
It returns summaries of the chats an Agent has access to.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/get_chats_summary |
| Required scopes | chats--all:ro chats--access:ro chats--my:ro |
| RTM API equivalent | get_chats_summary |
| Webhook | - |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
filters | No | object | Mustn't change between requests for subsequent pages. Otherwise, the behavior is undefined. |
filters.include_active | No | bool | Defines if the returned chat summary includes active chats; default: true. |
filters.group_ids | No | array | Array of group IDs. |
filters.properties.<namespace>.<name>.<filter_type> | No | any | |
order | No | string | Possible values: asc - oldest chats firstm desc - newest chats first (default) |
limit | No | number | Default: 10, maximum: 100 |
page_id | No | string |
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 |
|---|---|---|
found_chats | number | An estimated number. The real number of found chats can slightly differ. |
next_page_id | string | In relation to page_id specified in the request. |
previous_page_id | string | In relation to page_id specified in the request. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/get_chats_summary \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'
Response
Copied!
{
"next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
"chats_summary": [
{
"id": "PJ0MRSHTDG",
"last_event_per_type": {
"message": {
"thread_id": "K600PKZON8",
"thread_order": 1,
"event": {
"id": "Q298LUVPRH_1",
"created_at": "2019-12-09T12:01:18.909000Z",
"recipients": "all",
"type": "message",
"text": "hello world",
"author_id": "5ae8b076-03b0-43db-44f9-b95f8ead62e4"
}
},
"system_message": {
"thread_id": "K600PKZON8",
"thread_order": 1,
"event": {
// "System message" event
}
}
},
"users": [
{
// "Customer" user object
},
{
// "Agent" user object
}
],
"last_thread_summary": {
"id": "K600PKZON8",
"timestamp": 1575892853,
"user_ids": [
"5ae8b076-03b0-43db-44f9-b95f8ead62e4",
"customer1@example.com"
],
"order": 1,
"properties": {
// "Properties" object
},
"active": true,
"access": {
"group_ids": [0]
}
},
"properties": {
// "Properties" object
},
"access": {
"group_ids": [0]
},
"order": 1575892853242000,
"is_followed": true
}
],
"found_chats": 4
}
Get Chat Threads Summary
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/get_chat_threads_summary |
| Required scopes | chats--all:ro chats--access:ro chats--my:ro |
| RTM API equivalent | get_chat_threads_summary |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat_id | Yes | string | |
order | No | string | Possible values: asc - oldest chats first and desc - newest chats first (default). |
limit | No | number | Default: 10, maximum: 100 |
page_id | No | string |
Response
| Field | Data type | Notes |
|---|---|---|
found_threads | number | Number of threads in a chat |
next_page_id | string | In relation to page_id specified in the request. |
previous_page_id | string | In relation to page_id specified in the request. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/get_chat_threads_summary \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWJ8Y4THAV"
}'
Response
Copied!
{
"threads_summary": [
{
"id": "PT039ES4OG",
"order": 2,
"events_count": 2
},
{
"id": "PT039DS6IP",
"order": 1,
"events_count": 17
}
],
"found_threads": 7,
"next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
"previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
}
Get Chat Threads
It returns threads that the current Agent has access to in a given chat.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/get_chat_threads |
| Required scopes | chats--all:ro chats--access:ro |
| RTM API equivalent | get_chat_threads |
| Webhook | - |
Request
| Parameter | Required | Data type | |
|---|---|---|---|
chat_id | Yes | string | |
thread_ids | No | array |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/get_chat_threads \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWJ8Y4THAV"
}'
Response
Copied!
{
"chat": {
"id": "PWJ8Y4THAV",
"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": "agent1@example.com",
"name": "Agent Name",
"email": "agent1@example.com",
"type": "agent",
"present": true,
"avatar": "https://example.com/avatar.jpg"
}
],
"threads_summary": [
{
"thread_id": "Q20N9CKRX2",
"order": 1
}
],
"properties": {
// "Property" object
},
"access": {
"group_ids": [0]
},
"is_followed": true
}
}
Get 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.1/agent/action/get_archives |
| Required scopes | chats--all:ro chats--access:ro |
| RTM API equivalent | get_archives |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
filters | No | object | |
filters.query | No | string | |
filters.date_from | No | string | YYYY-MM-DD format |
filters.date_to | No | string | YYYY-MM-DD format |
filters.agent_ids | No | array | Array of agent IDs |
filters.thread_ids | No | array | Array of thread IDs. Cannot be used with other filters or pagination; max array size: 20. |
filters.group_ids | No | array | Array of group IDs |
filters.properties.<namespace>.<name>.<filter_type> | No | any | * described below |
filters.tags.<filter_type> | No | any | |
filters.sales.<filter_type> | No | any | |
filters.goals.<filter_type> | No | any | |
filters.surveys.<survey> | No | array | ** described below |
pagination | No | object | |
pagination.page | No | number | Default: 1, min: 1, max: 1000 |
pagination.limit | No | number | Default: 25, min: 0, max: 100 |
*)
sort_order can take the following values:
asc- the oldest chats firstdesc- the newest chats first
<filter_type> can take the following values:
exists(bool)values(type[]- an array with a specific type for property:string,intorbool)exclude_values(type[]- an array with a specific type for property:string,intorbool)
There's only one value allowed for a single property.
**)
<survey> contains the following fields:
type(string) - allowed values:pre_chat,post_chatanswer_id(string)
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/get_archives \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"filters": {
"thread_ids": ["K600PKZON8"]
}
}'
Response
Copied!
{
"chats": [
{
"id": "PJ0MRSHTDG",
"users": [
{
"id": "smith@example.com",
"name": "Agent Smith",
"email": "smith@example.com",
"type": "agent",
"present": true,
"avatar": "https://cdn.livechatinc.com/cloud/?uri=avatar.jpg"
}
],
"thread": {
"id": "K600PKZON8",
"timestamp": 1590666298,
"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": {
"value": "property_value"
}
}
},
"text": "Hello, how can I help you?",
"author_id": "smith@example.com"
}
],
"order": 1,
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"thread_property": {
"value": "property_value"
}
}
},
"access": {
"group_ids": [
0
]
}
},
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"chat_property": {
"value": "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.1/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_thread |
*)
When chat.users is defined, one of following scopes is required:
chats--all:rwchats--access:rwchats--my:rw
Request
| Parameters | Required | Data type | Notes |
|---|---|---|---|
chat | No | object | |
chat.properties | No | object | |
chat.access | No | object | |
chat.users | No | array | The list of existing users. Only one user is allowed (type customer). |
chat.thread | No | object | |
chat.thread.events | No | array | The list of initial chat events. |
chat.thread.properties | No | object | |
continuous | No | bool | Starts chat as continuous (online group is not required); default: false. |
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. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/start_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "PGDGHT5G"
}
Activate Chat
Restarts an archived chat.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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_thread |
*)
When chat.users is defined, one of following scopes is required:
chats--all:rwchats--access:rwchats--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 | array | The list of existing users. Only one user is allowed (type customer). |
chat.thread | No | object | |
chat.thread.events | No | array | Initial chat events array |
chat.thread.properties | No | object | Initial chat thread properties |
continuous | No | bool | Sets a chat to the continuous mode. When unset, leaves the mode unchanged. |
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. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/activate_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat": {
"id": "PWJ8Y4THAV"
}
}'
Response
Copied!
{
"thread_id": "Z8AGR5OUW"
}
Close Thread
Closes a thread. Sending messages to this thread will no longer be possible.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/close_thread |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | close_thread |
| Webhook | thread_closed |
Request
| Parameter | Required | Data type | |
|---|---|---|---|
chat_id | Yes | string |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/close_thread \
-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.1/agent/action/follow_chat |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | follow_chat |
| Webhook | incoming_chat_thread* |
*) It won't be sent when the requester already follows the chat or is the chat member.
Request
| Parameter | Required | Data type | |
|---|---|---|---|
chat_id | Yes | string |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/unfollow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWF6BACIKO"
}'
Chat access
Grant Access
Grants access to a new resource without overwriting the existing ones.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/grant_access |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | grant_access |
| Webhook | access_granted |
Request
| Parameter | Required | Data ype | Notes |
|---|---|---|---|
resource | Yes | string | chat or customer |
id | Yes | string | Resource Id |
access | Yes | object | The entity that is granted access to the specified resource |
access.type | Yes | string | group |
access.id | Yes | number |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/grant_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"resource": "chat",
"id": "PW94SJTGW6",
"access": {
"type": "group",
"id": 19
}
}'
Revoke Access
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/revoke_access |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | revoke_access |
| Webhook | access_revoked |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
resource | Yes | string | chat or customer |
id | Yes | string | Resource Id |
access | Yes | object | The entity that loses access to the specified resource |
access.type | Yes | string | group |
access.id | Yes | number |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/revoke_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"resource": "chat",
"id": "PW94SJTGW6",
"access": {
"type": "group",
"id": 19
}
}'
Set Access
Gives access to a new resource overwriting the existing ones.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/set_access |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | set_access |
| Webhook | access_set |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
resource | Yes | string | chat or customer |
id | Yes | string | resource id |
access | Yes | object | The entity that is given access to the specified resource |
access.type | Yes | string | group |
access.id | Yes | number |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/set_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"resource": "chat",
"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.1/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 ype | Notes |
|---|---|---|---|
chat_id | Yes | string | Resource 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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/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 | chat_user_added |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
chat_id | Yes | string | |
user_id | Yes | string | |
user_type | Yes | string | Possible values: agent or customer |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/add_user_to_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"user_id": "agent1@example.com",
"user_type": "agent"
}'
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.1/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 | chat_user_removed |
Request payload
| Parameter | Required | Type | Notes |
|---|---|---|---|
chat_id | Yes | string | |
user_id | Yes | string | |
user_type | Yes | string | Possible values are agent or customer |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/remove_user_from_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"user_id": "agent1@example.com",
"user_type": "agent"
}'
Events
Send Event
Sends an Event object. Use this method to send a message by specifing 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 chat_user_added). Sample use case: a Bot Agent that sends messages visible to all chat participants without actually joining the chat.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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 |
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 |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/send_event \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"event": {
"type": "message",
"text": "hello world",
"recipients": "all"
}
}'
Response
Copied!
{
"event_id": "K600PKZON8"
}
Upload File
Uploads a file to the server as a temporary file. It returns a URL that expires after 24 hours unless the URL is used in send_event.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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 |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/upload_file \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: multipart/form-data; boundary=--------------------------210197025774705439685896' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file=@/Users/MyAccount/Desktop/image.png
Response
Copied!
{
"url": "https://cdn.livechat-files.com/api/file/lc/att/8948324/45a3581b59a7295145c3825c86ec7ab3/image.png"
}
Send Rich Message Postback
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}'
Delete Chat Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/delete_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": [
"score",
"comment"
]
}
}'
Update Chat Thread Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/update_chat_thread_properties |
| Required scopes | chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw |
| RTM API equivalent | update_chat_thread_properties |
| Webhook | chat_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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_chat_thread_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}'
Delete Chat Thread Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/delete_chat_thread_properties |
| Required scopes | chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw |
| RTM API equivalent | delete_chat_thread_properties |
| Webhook | chat_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 | Chat thread properties to delete. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/delete_chat_thread_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": [
"score",
"comment"
]
}
}'
Update Event Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"event_id": "2_EW2WQSA8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}'
Delete Event Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/delete_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"event_id": "2_EW2WQSA8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"rating": [
"score",
"comment"
]
}
}
}'
Thread tags
Tag Chat Thread
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/tag_chat_thread |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | tag_chat_thread |
| Webhook | chat_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 |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/tag_chat_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "PWS6GIKAKH",
"tag": "support"
}'
Untag Chat Thread
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/untag_chat_thread |
| Required scopes | chats--all:rw chats--access:rw chats--my:rw |
| RTM API equivalent | untag_chat_thread |
| Webhook | chat_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 |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/untag_chat_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "PWS6GIKAKH",
"tag": "support"
}'
Customers
Get Customers
It returns the list of Customers.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/get_customers |
| Required scopes | customers:ro |
| RTM API equivalent | get_customers |
| Webhook | - |
Request
All parameters are optional.
| Parameter | Data type | Notes |
|---|---|---|
page_id | string | |
limit | number | Default: 10, maximum: 100 |
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 |
*)
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. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/get_customers \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
"customers": [
// array of "User > Customer" objects
],
"total_customers": 2340,
"next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
"previous_page_id": "MTUxNzM5ODEzMTQ5Ng==" // optional
}
Create Customer
Creates a new Customer user type.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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 |
fields | No | object | A map in the "key": "value" format |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/create_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
Update Customer
Updates Customer's properties.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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 |
fields | No | object | A map in the "key": "value" format |
Apart from customer_id, which is a required parameter, you also need to include one of the optional parameters.
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "646d53b8-ba76-48bf-7ef1-f6d61ec4ec44",
"name": "John Doe"
}'
Response
Copied!
{
// "User > Customer" object
}
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.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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
Update Agent
Updates Agent's properties.
Specifics
| Method URL | https://api.livechatinc.com/v3.1/agent/action/update_agent |
| Required scopes | agents--my:rw agents--all:rw |
| RTM API equivalent | update_agent |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
agent_id | No | string | The current Agent is used by default. |
routing_status | No | string | Possible values: accepting_chats, not_accepting_chats |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "agent1@example.com",
"routing_status": "accepting_chats"
}'
Other
Mark Events as Seen
Specifics
| Method URL | https://api.livechatinc.com/v3.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/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).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/agent/action/multicast |
| Required scopes | multicast:rw |
| RTM API equivalent | multicast |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
scopes | Yes | object | * |
content | Yes | any | A JSON message to be sent |
type | No | string | Multicast message type |
*) scopes 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 scopes type (agents.all, agents.ids, agents.groups, customers.ids) is required.
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/multicast \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"scopes": {
"agents": {
"all": true,
"ids": [
"agent1@example.com",
"agent2@example.com"
],
"groups": [
1,
2
]
},
"customers": {
"ids": [
"b7eff798-f8df-4364-8059-649c35c9ed0c"
]
}
},
"content": {
"example": {
"nested": "json"
}
}
}'
Webhooks
Here's what you need to know about webhooks:
- Webhooks notify you when specific events occur.
- 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.
- To receive webhooks, you need to register them first. You can do it via the Configuration API.
Errors
General error format
Copied!
{
"error": {
"type": "misdirected_request",
"message": "Wrong region",
"data": {
// optional
"region": "dal"
}
}
}
Possible errors
| Error type | Default message | Description |
|---|---|---|
authentication | Authentication error | An invalid or expired access token. |
authorization | Authorization error | User is not allowed to perform the action. |
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 | Resource 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. It helps to figure out 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 | Unsupported version | 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@livechat.com. We'll be happy to hear from you!