Web API Reference 5 minutes reading time
This document describes the Customer Chat Web API v3.2 . This is the latest stable version recommended for the production use. Read more about versioning...
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.
If you're wondering which API to use - Customer 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 Customer Chat RTM API instead.
Customer authentication is handled with access tokens. Find out how to get an access token from Customer authorization flow . Take note it's not the same token you would you for the Agent Chat or Configuration API.
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.
You can find all the requests from the Customer 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 the sample token with your own.
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 event informs about a file being uploaded.
Field Required Data type Notes custom_id
no string
type
yes string
file
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
.
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 properties
optionally name
always url
always thumbnail_url
, thumbnail2x_url
only for images content_type
always size
, width
, height
only for images
{
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z",
"type": "file",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"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 event contains data from a form (prechat or postchat survey).
Field Required Data type Notes custom_id
no string
type
yes string
filled_form
properties
no object
Properties form_id
yes string
fields
yes array
The fields a form contains. See form fields for details.
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 properties
optionally form_id
always fields
always An array of form fields
Sample Filled form in response {
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z",
"type": "filled_form",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"form_id": "1473433500211",
"fields": [
{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "Thomas Anderson"
},
{
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "t.anderson@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": {
"id": "2",
"group_id": 1,
"label": "Marketing"
}
}
]
}
Message event contains text message to other chat users.
Field 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
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).
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 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 {
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z",
"type": "message",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"text": "hello there",
"postback": {
"id": "action_call",
"thread_id": "K600PKZON8",
"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
"type": "phone",
"value": "790034890"
},
"properties": {
"property_namespace": {
"property_name": "property_value"
}
}
}
Rich message event contains rich message data structure. Read more in a document dedicated to Rich messages.
Field Required Data type Notes custom_id
no string
You can give your RM a custom ID. type
yes string
Event type: rich_message
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 13 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
.
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. 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 {
"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",
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"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 event is an event with customizable payload.
Field 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 properties
no object
The properties data structure
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 properties
optionally
Sample Custom event in response {
"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"
}
},
"properties": {
"property_namespace": {
"property_name": "property_value"
}
}
}
System message event is a native system event sent in specific situations.
Field 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 text_vars
no object
Variables used in the text
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
Sample System message in response {
"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"custom_id": "31-0C-1C-07-DB-16",
"created_at": "2017-10-12T15:19:21.010200Z",
"type": "system_message",
"text": "hello there",
"system_message_type": "routing.assigned",
"text_vars": {
"agent": "John Doe"
}
}
Users are another important data structure. Within this data structure type, we can distinguish:
Sample Customer data structure {
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"avatar": "https://example.com/avatar.png",
"session_fields": [
{
"custom_key": "custom_value"
},
{
"another_custom_key": "another_custom_value"
}
],
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Field Req./Opt. Notes avatar
optional email
optional name
optional session_fields
optional An array of custom object-enclosed key:value
pairs. Available for the session duration.
Sample Agent data structure {
"id": "b5657aff34dd32e198160d54666df9d8",
"type": "agent",
"name": "Agent Smith",
"avatar": "cdn.livechatinc.com/avatars/1.png",
"present": true,
"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
Apart from Events and Users , there are also other common data structures you might work with. Those are:
Sample Access data structure {
"access": {
"group_ids": [
1,
2
]
}
}
Field Req./Opt. Note group_ids
required group 0
means that all agents can see it.
Sample Chat data structure {
"id": "PJ0MRSHTDG",
"threads": [
{
"id": "QA1B38GHGI",
"created_at": "2020-05-07T07:11:28.288340Z",
"active": false,
"user_ids": [
"bbb67d600796e9f277e360e842418833",
"b7eff798-f8df-4364-8059-649c35c9ed0c"
],
"events": [
{
"id": "QA1B38GHGI_1",
"created_at": "2020-05-14T07:22:40.269000Z",
"type": "message",
"properties": {
"source": {
"client_id": "0805e283233042b37f460ed8fbf22160"
}
},
"text": "hello",
"author_id": "bbb67d600796e9f277e360e842418833",
"custom_id": "1589440960204.71699349177"
},
{
"id": "QA1B38GHGI_3",
"created_at": "2020-05-14T08:18:44.015000Z",
"type": "system_message",
"text": "The chat was closed because Agent Smith had lost internet connection",
"system_message_type": "routing.archived_disconnected",
"text_vars": {
"agent": "Agent Smith"
}
}
],
"properites": {
"property_namespace": {
"property_name": "property_value"
}
},
"access": {
"group_ids": [
0
]
},
"previous_thread_id": "K600PKZOM8",
"next_thread_id": "K600PKZOO8"
}
],
"users": [
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"present": true
},
{
"id": "bbb67d600796e9f277e360e842418833",
"name": "Agent Smith",
"events_seen_up_to": "2020-05-14T07:22:37.287496Z",
"type": "agent",
"present": false,
"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png",
"job_title": "Support Agent"
}
],
"access": {
"group_ids": [
0
]
},
"properites": {
"property_namespace": {
"property_name": "property_value"
}
}
}
Field Req./Opt. Note properties
optional access
optional
Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread
object, while Chat summary includes last_event_per_type
.
Sample Chat summary data structure {
"id": "PJ0MRSHTDG",
"last_thread_id": "QA1B38GHGI",
"last_thread_created_at": "2020-05-08T08:22:21.128420Z",
"users": [
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"present": true
},
{
"id": "bbb67d600796e9f277e360e842418833",
"name": "Agent Smith",
"events_seen_up_to": "2020-05-14T07:22:37.287496Z",
"type": "agent",
"present": false,
"avatar": "https://cdn.livechatinc.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png",
"job_title": "Support Agent"
}
],
"last_event_per_type": {
"message": {
"thread_id": "QA1B38GHGI",
"thread_order": 1,
"thread_created_at": "2020-05-14T07:22:30.779000Z",
"event": {
"id": "QA1B38GHGI_1",
"created_at": "2020-05-14T07:22:40.269000Z",
"type": "message",
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"text": "Hello",
"author_id": "bbb67d600796e9f277e360e842418833",
"custom_id": "1589440960204.71699349177"
}
},
"system_message": {
"thread_id": "QA1B38GHGI",
"thread_order": 1,
"thread_created_at": "2020-05-14T07:22:30.779000Z",
"event": {
"id": "QA1B38GHGI_3",
"created_at": "2020-05-14T08:18:44.015000Z",
"type": "system_message",
"text": "The chat was closed because Agent Smith had lost internet connection",
"system_message_type": "routing.archived_disconnected",
"text_vars": {
"agent": "Agent Smith"
}
}
}
},
"properites": {
"property_namespace": {
"property_name": "property_value"
}
},
"access": {
"group_ids": [
0
]
},
"active": false
}
A component of the Filled form event.
{
"fields": [
{
"type": "name",
"id": "154417206262603539",
"label": "Your name",
"answer": "Thomas Anderson"
},
{
"type": "email",
"id": "154417206262601584",
"label": "Your email",
"answer": "t.anderson@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": {
"id": "2",
"group_id": 1,
"label": "Marketing"
}
}
]
}
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
An identifier of each option a Customer can choose. For all field types. answer.label
yes string
Answer label; for all field types answer.group_id
yes number
For group_chooser
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 {
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
}
Sample Thread data structure {
"id": "K600PKZON8",
"active": true,
"user_ids": [
"b7eff798-f8df-4364-8059-649c35c9ed0c"
],
"events": [
{
"id": "QA1B38GHGI_1",
"created_at": "2020-05-14T07:22:40.269000Z",
"type": "message",
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"text": "hello",
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"custom_id": "1589440960204.71699349177"
}
],
"properties": {
"property_namespace": {
"property_name": "property_value"
}
},
"access": {
"group_ids": [
0
]
},
"queue": {
"position": 42,
"wait_time": 1337,
"queued_at": "2020-05-07T07:11:28.288340Z"
},
"previous_thread_id": "K600PKZOM8",
"next_thread_id": "K600PKZOO8",
"created_at": "2020-05-07T07:11:28.288340Z"
}
Field Req./Opt. Note access
optional active
required Possible values: true
(thread is still active) or false
(thread no longer active). events
optional properties
optional queue
optional Present only if the chat is in the queue. The wait time for an available agent is approximated in seconds. previous_thread_id
optional Present only if there is a preceding thread. next_thread_id
optional Present only if there is a following thread. created_at
required Date & time format with a resolution of microseconds, UTC string
. Generated server-side.
HTTP method The API endpoint Methods POST https://api.livechatinc.com/v3.2/customer/action/<action>
All except for Get License Properties and Get Group Properties GET https://api.livechatinc.com/v3.2/customer/action/<action>
Get License Properties and Get Group Properties
Header Value Notes X-API-Version
3.2
Not needed if you specify the API version in the URL. Content-Type
multipart/form-data; boundary=<boundary>
Valid for the Upload File method Content-Type
application/json
Valid for every method except for Upload File Authorization
Bearer <token>
Customer access token. It's not the same token you would use for the Agent Chat or Configuration API. Not needed for Get License Properties and Get Group Properties . Read more...
Every request to Customer Chat API needs to have the following query string parameters :
Query string parameter Data type Notes Methods license_id
integer
LiveChat account ID All
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
// payload
}'
It returns summaries of the chats a Customer participated in.
Method URL https://api.livechatinc.com/v3.2/customer/action/list_chats
RTM API equivalent list_chats
Webhook -
Parameter Required Type Notes limit
No number
Default: 10, maximum: 25 sort_order
No string
Possible values: asc
, desc
(default). Chat summaries are sorted by the creation date of its last thread. page_id
No string
Parameter Data type Notes total_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. Appears in the response only when there's the next page. previous_page_id
string
In relation to page_id
specified in the request. Appears in the response only when there's the previous page. chats_summary
array
Array of Chat summary data structures.
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/list_chats?license_id= < license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
{
"next_page_id" : "MTUxNzM5ODEzMTQ5Ng==" ,
"chats_summary" : [ {
"id" : "PJ0MRSHTDG" ,
"last_thread_id" : "K600PKZON8" ,
"last_thread_created_at" : "2020-05-08T08:22:21.128420Z" ,
"last_event_per_type" : {
"message" : {
"thread_id" : "K600PKZON9" ,
"thread_created_at" : "2020-05-07T07:11:28.288340Z" ,
"event" : {
"id" : "Q298LUVPRH_1" ,
"created_at" : "2019-12-09T12:01:18.909000Z" ,
"type" : "message" ,
"text" : "hello world" ,
"author_id" : "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
}
} ,
"users" : [ {
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"type" : "customer" ,
"present" : true
} , {
"id" : "b5657aff34dd32e198160d54666df9d8" ,
"name" : "Agent Smith" ,
"type" : "agent" ,
"present" : true ,
"avatar" : "https://example.com/avatar.png" ,
"job_title" : "Support Agent"
} ] ,
"access" : {
"group_ids" : [ 0 ]
} ,
"properties" : {
"Properties" object
} ,
"active" : true
} ] ,
"total_chats" : 1
}
It returns threads that the current Customer has access to in a given chat.
Method URL https://api.livechatinc.com/v3.2/customer/action/list_threads
RTM API equivalent list_threads
Webhook -
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.
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/list_threads \
-H 'Authorization: Bearer <customer_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" ,
"bbb67d600796e9f277e360e842418833"
] ,
"events" : [ {
"id" : "Q20N9CKRX2_1" ,
"created_at" : "2019-12-17T07:57:41.512000Z" ,
"recipients" : "all" ,
"type" : "message" ,
"text" : "Hello" ,
"author_id" : "bbb67d600796e9f277e360e842418833"
} ] ,
"properties" : {
"Property" object
} ,
"access" : {
"group_ids" : [ 0 ]
} ,
"previous_thread_id" : "K600PKZOM8" ,
"next_thread_id" : "K600PKZOO8"
} ] ,
"found_threads" : 42 ,
"next_page_id" : "MTUxNzM5ODEzMTQ5Ng==" ,
"previous_page_id" : "MTUxNzM5ODEzMTQ5Nw=="
}
Method URL https://api.livechatinc.com/v3.2/customer/action/get_chat
RTM API equivalent get_chat
Webhook -
Parameter Required Data type Notes chat_id
Yes string
thread_id
No string
Default: the latest thread (if exists)
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/get_chat?license_id= < license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"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" ,
"b5657aff34dd32e198160d54666df9d8"
] ,
"events" : [ {
"id" : "Q20N9CKRX2_1" ,
"created_at" : "2019-12-17T07:57:41.512000Z" ,
"type" : "message" ,
"text" : "Hello" ,
"author_id" : "b5657aff34dd32e198160d54666df9d8"
} ] ,
"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
} , {
"id" : "b5657aff34dd32e198160d54666df9d8" ,
"name" : "Agent Smith" ,
"type" : "agent" ,
"present" : true ,
"avatar" : "https://example.com/avatar.jpg" ,
"job_title" : "Support Agent"
} ] ,
"access" : {
"group_ids" : [ 0 ]
} ,
"properties" : {
"0805e283233042b37f460ed8fbf22160" : {
"string_property" : "string_value"
}
}
}
Starts a chat.
Method URL https://api.livechatinc.com/v3.2/customer/action/start_chat
RTM API equivalent start_chat
Webhook incoming_chat
Parameters Required Data type Notes chat
No object
chat.properties
No object
Initial chat properties chat.access
No object
Chat access to set; default: all agents. chat.thread
No object
chat.thread.events
No array
Initial chat events array chat.thread.properties
No object
Initial thread properties continuous
No bool
Starts chat as continuous (online group is not required); default: false
.
Parameter 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.
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/start_chat?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
{
"chat_id" : "PJ0MRSHTDG" ,
"thread_id" : "PGDGHT5G"
}
Used to restart an archived chat.
Request object Required 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.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.
Parameter 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.
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/activate_chat?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat": {
"id": "PWLW03ICW7"
}
}'
{
"thread_id" : "Z8AGR5OUW"
}
Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible.
Parameter Required Data type chat_id
Yes string
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/deactivate_chat?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PWLW03ICW7"
}'
Sends an Event object. Use this method to send a message by specifying the Message event type in the request.
The method updates the requester's events_seen_up_to
as if they've seen all chat events.
Parameters Required Data type Notes chat_id
Yes string
Id of the chat that you to send a message to. event
Yes object
The event object attach_to_last_thread
No bool
If true
, adds an event to last (inactive) thread. Otherwise, it doesn't creates a new one; default: false
.
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/send_event?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWLW03ICW7",
"event": {
"type": "message",
"text": "hello world",
"recipients": "all"
}
}'
{
"event_id" : "K600PKZON8"
}
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
.
Method URL https://api.livechatinc.com/v3.2/customer/action/upload_file
RTM API equivalent - Webhook incoming_event
*
*)
incoming_event
returns a URL that never expires.
Parameter Required Data type Notes file
Yes binary
Maximum size: 10MB
curl -X POST \
https://api.livechatinc.com/v3.2/customer/action/upload_file?license_id= < license_id> \
-H 'Authorization: Bearer <customer_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"
}
*) incoming_rich_message_postback
will be sent only for active threads.
Parameter Required Data type Notes chat_id
Yes string
event_id
Yes string
postback
Yes object
postback.id
Yes string
Postback name of the button postback.toggled
Yes bool
Postback toggled; true
or false
thread_id
Yes string
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/send_rich_message_postback?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
"postback": {
"id": "Method URL_yes",
"toggled": true
}
}'
Sends a sneak peek to a chat.
Method URL https://api.livechatinc.com/v3.2/customer/action/send_sneak_peek
RTM API equivalent send_sneak_peek
Webhook -
Parameter Required Data type Notes chat_id
Yes string
Id of the chat to send a sneak peek to. sneak_peek_text
Yes string
Sneak peek text
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/send_sneak_peek?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"sneak_peek_text": "hello world"
}'
Parameter Required Data type Notes chat_id
Yes string
Id of the chat you to set a property for. properties
Yes object
Chat properties to set. You should stick to the general properties format and include namespace , property name and value .
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/update_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "Chat property value updated by Customer"
}
}
}'
Parameter Required Data type Notes chat_id
Yes string
Id of the chat you want to delete properties of. properties
Yes object
Chat properties to delete.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/delete_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
}'
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.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/update_thread_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"thread_id": "Q1GZ3FNAU9",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "Thread property value updated by Customer"
}
}
}'
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. properties
Yes object
Thread properties to delete.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/delete_thread_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"thread_id": "Q1GZ3FNAU9",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
}'
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 .
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/update_event_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"thread_id": "Q1GZ3FNAU9",
"event_id": "Q1GZ3FNAU9_1",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "Event property value updated by Customer"
}
}
}'
Parameter Required Data type Notes chat_id
Yes string
Id of the chat you want to delete the properties of. thread_id
Yes string
Id of the thread you want to delete the properties of. event_id
Yes string
Id of the event you want to delete the properties of. properties
Yes object
Event properties to delete. You should stick to the general properties format and include namespace , property name and value .
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/delete_event_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "Q1GZ3FNAT9",
"thread_id": "Q1GZ3FNAU9",
"event_id": "Q1GZ3FNAU9_1",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
}'
Returns the properties of a given license. It only returns the properties a Customer has access to.
HTTP Method GET Method URL https://api.livechatinc.com/v3.2/customer/action/list_license_properties
RTM API equivalent - Webhook -
Query string parameter Required Data type Notes license_id
Yes number
Id of the license you want to return the properties of. namespace
No string
Property namespace to retrieve name
No string
Property name
curl -X GET \
'https://api.livechatinc.com/v3.2/customer/action/list_license_properties?license_id=123&namespace=0805e283233042b37f460ed8fbf22160&name=string_property' \
-H 'Content-Type: application/json'
{
"0805e283233042b37f460ed8fbf22160" : {
"string_property" : "string value"
}
}
Returns the properties of a given group. It only returns the properties a Customer has access to.
HTTP Method GET Method URL https://api.livechatinc.com/v3.2/customer/action/list_group_properties
RTM API equivalent - Webhook -
Query string parameter Required Data type Notes license_id
Yes number
Id of the license you want to return the properties of. group_id
Yes number
Id of the group you want to return the properties of. namespace
No string
Property namespace to retrieve name
No string
Property name
curl -X GET \
'https://api.livechatinc.com/v3.2/customer/action/list_group_properties?license_id=11069052&group_id=1&namespace=0805e283233042b37f460ed8fbf22160&name=string_property' \
-H 'Content-Type: application/json'
{
"0805e283233042b37f460ed8fbf22160" : {
"string_property" : "string value"
}
}
Method URL https://api.livechatinc.com/v3.2/customer/action/update_customer
RTM API equivalent update_customer
Webhook -
Parameter Required Data type Notes name
No string
email
No string
avatar
No string
The URL of the Customer's avatar session_fields
No []object
An array of custom object-enclosed key:value
pairs. Respects the order of items.
At least one optional parameter needs to be included in the request.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/update_customer?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"avatar": "example.com/avatars/1.png",
"session_fields": [{
"custom_key": "custom_value"
}, {
"another_custom_key": "another_custom_value"
}]
}'
Method URL https://api.livechatinc.com/v3.2/customer/action/set_customer_session_fields
RTM API equivalent set_customer_session_fields
Webhook -
Parameter Required Data type Notes session_fields
Yes []object
An array of custom object-enclosed key:value
pairs. Respects the order of items. Max keys: 100
Users Agent and referrer are updated by default using the browser’s headers.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/set_customer_session_fields?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"session_fields": [{
"custom_key": "custom_value"
}, {
"another_custom_key": "another_custom_value"
}]
}'
Returns the info about the Customer requesting it.
Method URL https://api.livechatinc.com/v3.2/customer/action/get_customer
RTM API equivalent get_customer
Webhook -
name
Customer's name. Returned only if set.email
Customer's email. Returned only if set.avatar
Customer's avatar. Returned only if set.session_fields
An array of custom object-enclosed key:value
pairs. Returned only if set. Available for the session duration.
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/get_customer?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
{
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"type" : "customer" ,
"name" : "Thomas Anderson" ,
"email" : "t.anderson@example.com" ,
"avatar" : "https://example.com/avatars/1.jpg" ,
"session_fields" : [ {
"custom_key" : "custom_value"
} , {
"another_custom_key" : "another_custom_value"
} ]
}
Method URL https://api.livechatinc.com/v3.2/customer/action/list_group_statuses
RTM API equivalent list_group_statuses
Webhook -
Parameter Required Data type Notes all
No bool
If set to true
, you will get statuses of all the groups. group_ids
No array
A table of groups' IDs
One of the optional parameters needs to be included in the request.
No response payload (200 OK
).
Group Not Found
If you send group_id
of a group that doesn't exists, the id won't be included in the resposne.
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/list_group_statuses?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"all": true
}'
{
"groups_status" : {
1 : "online" ,
2 : "offline" ,
3 : "online_for_queue"
}
}
Customer can use this method to trigger checking if goals were achieved. Then, Agents receive the information. You should call this method to provide goals parameters for the server when the customers limit is reached. Works only for offline Customers.
Method URL https://api.livechatinc.com/v3.2/customer/action/check_goals
RTM API equivalent - Webhook -
Parameter Required Data type Notes session_fields
Yes []object
An array of custom object-enclosed key:value
pairs group_id
Yes number
page_url
Yes string
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/check_goals?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"page_url": "https://mypage.com",
"session_fields": [{
"custom_key": "custom_value"
}, {
"another_custom_key": "another_custom_value"
}],
"group_id": 0
}'
Returns an empty ticket form of a prechat or postchat survey .
Method URL https://api.livechatinc.com/v3.2/customer/action/get_form
RTM API equivalent get_form
Webhook -
Parameter Required Data type Notes group_id
Yes number
Id of the group from which you want the form. type
Yes string
Form type; possible values: prechat
or postchat
Parameter Notes enabled
If enabled: false
, the form
object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI. form
The form
object
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/get_form?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"group_id": 0,
"type": "prechat"
}'
{
"form" : {
"id" : "157986144052005549" ,
"fields" : [
{
"id" : "157986144052003238" ,
"type" : "header" ,
"label" : "Welcome to our LiveChat! Please fill in the form below before starting the chat."
} ,
{
"id" : "157986144052008371" ,
"type" : "name" ,
"label" : "Name:" ,
"required" : false
} ,
{
"id" : "157986144052005782" ,
"type" : "email" ,
"label" : "E-mail:" ,
"required" : false
} ,
{
"id" : "157986144052009331" ,
"type" : "group_chooser" ,
"label" : "Choose a department:" ,
"required" : true ,
"options" : [
{
"id" : "0" ,
"group_id" : 1 ,
"label" : "Marketing"
} ,
{
"id" : "1" ,
"group_id" : 2 ,
"label" : "Sales"
} ,
{
"id" : "2" ,
"group_id" : 0 ,
"label" : "General"
}
]
}
]
} ,
"enabled" : true
}
Gets the predicted Agent - the one the Customer will chat with when the chat starts. To use this method, the Customer needs to be logged in, which can be done via the login
method.
Method URL https://api.livechatinc.com/v3.2/customer/action/get_predicted_agent
RTM API equivalent get_predicted_agent
Webhook -
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/get_predicted_agent?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
{
"id" : "b5657aff34dd32e198160d54666df9d8" ,
"name" : "Agent Smith" ,
"avatar" : "https://example.avatar/example.com" ,
"is_bot" : false ,
"job_title" : "support hero" ,
"type" : "agent"
}
It returns the info on a given URL.
Method URL https://api.livechatinc.com/v3.2/customer/action/get_url_info
RTM API equivalent get_url_info
Webhook -
Parameter Required Data type Notes url
Yes string
Valid website URL
Parameter Data type Notes image_url
string
URL of the minified image hosted on the LiveChat's CDN image_original_url
string
URL of the original image
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/get_url_info?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"url": "https://livechatinc.com"
}'
{
"title" : "LiveChat | Live Chat Software and Help Desk Software" ,
"description" : "LiveChat - premium live chat software and help desk software for business. Over 24 000 companies from 150 countries use LiveChat. Try now, chat for free!" ,
"image_url" : "https://example.com/image.png" ,
"image_original_url" : "https://example-original-url.com/image.png" ,
"image_width" : 200 ,
"image_height" : 200 ,
"url" : "https://livechatinc.com"
}
Parameter Required Data type Notes chat_id
Yes string
seen_up_to
Yes string
RFC 3339 date-time format
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/mark_events_as_seen?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
}'
Marks an incoming greeting as seen.
How it's implemented in LiveChat:
The Chat Widget uses this method to inform that a Customer has seen a greeting. Based on that, the Reports section displays the greetings
that were actually seen by Customers, not all the sent greetings. If a Customer started a chat from a greeting, but the Accept Method wasn't executed,
the greeting is still counted as seen in Reports.
Method URL https://api.livechatinc.com/v3.2/customer/action/accept_greeting
RTM API equivalent accept_greeting
Webhook -
Parameter Required Data type Notes greeting_id
Yes number
ID of the greeting configured within the license to accept. unique_id
Yes string
ID of the greeting to accept. You can get it from the incoming_greeting
push.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/accept_greeting?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"greeting_id": 7,
"unique_id": "Q10X0W041P"
}'
Cancels a greeting (an invitation to the chat). For example, Customers could cancel greetings by minimalizing the chat widget with a greeting.
Method URL https://api.livechatinc.com/v3.2/customer/action/cancel_greeting
RTM API equivalent cancel_greeting
Webhook -
Parameter Required Data type Notes unique_id
Yes string
ID of the greeting to cancel. You can get it from the incoming_greeting
push.
No response payload (200 OK
).
curl -X POST \
'https://api.livechatinc.com/v3.2/customer/action/cancel_greeting?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"unique_id": "Q10X0W041P"
}'
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 . Refer to this document to see the list of available webhooks , as well as sample payloads .
{
"error" : {
"type" : "misdirected_request" ,
"message" : "Wrong region" ,
"data" : {
"region" : "dal"
}
}
}
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. customer_banned
Customer is banned The customer had been banned. entity_too_large
Upload limit exceeded (10MB). Client's request is too large. greeting_not_found
Greeting not found group_not_found
Group not found group_offline
Group is offline Thrown in response to Get Predicted Agent. group_unavailable
No agent available for group Thrown in response to Get Predicted Agent. The group is online, but there are no available Agents. groups_offline
Groups offline 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. 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. 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).
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@livechatinc.com . We'll be happy to hear from you!