Web API Reference
Introduction
Versioning
This document describes the Customer Chat Web API v3.3. This is the latest stable version recommended for the production use. 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 - 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.
Access
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.
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.
Pagination
Pagination is a mechanism that allows splitting the database output into more manageable chunks of data.
Based on the limit and sort order parameters, pagination is able to decide how many records will be returned at once and whether it should fetch the oldest or the latest data first.
Any filters that could be applied should be provided in first pagination request. In the response, you'll get the next_page_id and previous_page_id parameters.
You should make the subsequent request using one of these parameters as page_id, depending on the direction of iteration: forward or backward.
The filters, limit, and sort_order parameters can't be provided along with page_id.
💡 The maximum duration of the page_id parameter before it expires is one month.
Postman collection
You can find all the requests from the Customer Chat Web API v3.3 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace sample tokens with your own.
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
File event informs about a file being uploaded.
Request
| Parameter | 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. |
alternative_text | no | string | Only applicable to images |
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 | |
properties | optionally | |
name | always | |
url | always | |
thumbnail_url, thumbnail2x_url | only for images | |
content_type | always | |
size, width, height | only for images | |
alternative_text | only for images |
Sample File in response
Copied!
{
"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,
"alternative_text": "A sample image"
}Form
The Form event contains an empty form to be sent in the chat. It doesn't matter how the form is configured or what fields it has – it can be any event of type form.
Request
| Field | Required | Data type | Notes |
|---|---|---|---|
custom_id | no | string | |
type | yes | string | form |
properties | no | object | Properties |
form_id | yes | string | |
fields | yes | array | The fields a form contains. See 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 | optionally | If form is generated by system, then this field is omitted. |
properties | optionally | |
form_id | always | |
fields | always | An array of form fields |
Sample Form in response
Copied!
{
"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"
}
]
}
]
}Filled form
Filled form event contains data from a form (prechat or postchat survey).
Request
| Field | 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 | |
properties | optionally | |
form_id | always | |
fields | always | The fields a form contains. See filled form fields for details. |
Sample Filled form in response
Copied!
{
"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
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 |
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 | |
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",
"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
Rich message event contains rich message data structure. Read more in a document dedicated to 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 |
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, alternative_text. |
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. You can use this field to give the rich message of a webview type (a Moment) a custom title. More... |
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. |
elements.buttons.target | no | string | Should be used for the url button type. Specifies if the URL should open in the current or a new tab. Possible values: new, current. |
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. |
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 | |
elements.buttons.target | optionally |
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",
"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,
"alternative_text": "A picture of lorem ipsum"
},
"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": [],
"target": "current"
}
]
}
]
}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 |
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 | |
properties | optionally |
Sample Custom event 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"
}
},
"properties": {
"property_namespace": {
"property_name": "property_value"
}
}
}System message
System message event is a 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 |
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 |
Sample System message in response
Copied!
{
"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
Users are another important data structure. Within this data structure type, we can distinguish:
Customer
Sample Customer data structure
Copied!
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"name": "Thomas Anderson",
"email": "t.anderson@example.com",
"email_verified": false,
"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 | |
email_verified | optional | Specifies if the customer confirmed their email address. See Request Email Verification. |
name | optional | |
session_fields | optional | An array of custom object-enclosed key:value pairs. Available for the session duration. |
Agent
Sample Agent data structure
Copied!
{
"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"
}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",
"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 summaries
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
Copied!
{
"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
}Forms
A template of a prechat, postchat, or a ticket form.
Sample Form data structure
Copied!
{
"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"
}
]
}
]
}| Field | Required | Data type | Notes |
|---|---|---|---|
id | no | string | Form ID |
fields | yes | array of objects | The fields a form contains |
fields.type | yes | string | Possible values: header, checkbox, email, name, question, subject, textarea, group_chooser, radio, select |
fields.id | no | string | Field ID, for all field types |
fields.label | yes | string | Field label, for all field types |
fields.required | no | bool | Determines whether the answer for given field is required, for all field types except header |
fields.options | no | array of objects | For checkbox, group_chooser, radio and select |
fields.options.id | yes | string | An identifier of each option a Customer can choose |
fields.options.label | yes | string | Answer label |
fields.options.group_id | yes | number | For group_chooser |
Form fields
A component of the Form event.
Sample Form fields
Copied!
{
"fields": [
{
"type": "name",
"id": "154417206262603539",
"label": "Your name"
},
{
"type": "email",
"id": "154417206262601584",
"label": "Your email"
},
{
"type": "radio",
"id": "154417206262602571",
"label": "Chat purpose"
},
{
"type": "checkbox",
"id": "154417206262604640",
"label": "Company industry"
},
{
"type": "group_chooser",
"id": "154417206262605324",
"label": "Choose department"
}
]
}| Field | Required | Data type | Notes |
|---|---|---|---|
fields | yes | array of objects | The fields a form contains. |
type | yes | string | Possible values: checkbox, email, name, question, subject, textarea, group_chooser, radio, select |
id | yes | string | Field id, for all field types |
label | yes | string | Field label; for all field types |
Filled form fields
A component of the Filled form event.
Sample Form fields
Copied!
{
"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, subject, 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
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": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
}Threads
Sample Thread data structure
Copied!
{
"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. |
Methods
| HTTP method | The API endpoint | Methods |
|---|---|---|
| POST | https://api.livechatinc.com/v3.3/customer/action/<action> | All except for List License Properties, List Group Properties, Dynamic Config, Config and Localization |
| GET | https://api.livechatinc.com/v3.3/customer/action/<action> | List License Properties, List Group Properties, Get Dynamic Configuration, Get Configuration and Get Localization |
| Header | Value | Notes |
|---|---|---|
X-API-Version | 3.3 | 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 |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/customer/action?license_id=<license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
// payload
}'
Available methods
Chats
List Chats
It returns summaries of the chats a Customer participated in.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/list_chats |
| RTM API equivalent | list_chats |
| Webhook | - |
Request
| 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 |
Response
| Field | 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. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/customer/action/list_chats?license_id=<license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
Response
Copied!
{
"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
}
List Threads
It returns threads that the current Customer has access to in a given chat.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/list_threads |
| RTM API equivalent | list_threads |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat_id | Yes | string | |
sort_order | No | string | Possible values: asc - oldest threads first and desc - newest threads first (default). |
limit | No | number | Default: 3, maximum: 100 |
page_id | No | string | |
min_events_count | No | number | Range: 1-100; Specifies the minimum number of events to be returned in the response. It's the total number of events, so they can come from more than one thread. You'll get as many latest threads as needed to meet the min_events_count condition. |
You cannot use both limit and min_events_count at the same time.
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/customer/action/list_threads \
-H 'Authorization: Bearer <customer_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWJ8Y4THAV",
}'
Response
Copied!
{
"threads": [{
"id": "K600PKZON8",
"created_at": "2019-12-17T07:57:41.512000Z",
"active": true,
"user_ids": [
"b7eff798-f8df-4364-8059-649c35c9ed0c",
"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", // optional
"next_thread_id": "K600PKZOO8" // optional
}],
"found_threads": 42,
"next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
"previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
}
Get Chat
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_chat |
| RTM API equivalent | get_chat |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat_id | Yes | string | |
thread_id | No | string | Default: the latest thread (if exists) |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/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"
}'
Response
Copied!
{
"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"
}
}
}
Start Chat
Starts a chat.
The method updates the requester's events_seen_up_to as if they've seen all chat events.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/start_chat |
| RTM API equivalent | start_chat |
| Webhook | incoming_chat |
Request
| Parameter | 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 |
active | No | bool | When set to false, creates an inactive thread; default: true. |
continuous | No | bool | Starts chat as continuous (online group is not required); default: false. |
Response
| Field | Data type | Notes |
|---|---|---|
chat_id | string | |
thread_id | string | |
event_ids | []string | Returned only when the chat was started with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/customer/action/start_chat?license_id=<license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
Response
Copied!
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "PGDGHT5G"
}
Resume Chat
Restarts an archived chat.
The method updates the requester's events_seen_up_to as if they've seen all chat events.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/resume_chat |
| RTM API equivalent | resume_chat |
| Webhook | incoming_chat |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat | Yes | object | |
chat.id | Yes | string | ID of the chat that will be resumed. |
chat.access | No | object | Chat access to set; default: all agents. |
chat.properties | No | object | Initial chat properties |
chat.thread | No | object | |
chat.thread.events | No | array | Initial chat events array |
chat.thread.properties | No | object | Initial thread properties |
active | No | bool | When set to false, creates an inactive thread; default: true. |
continuous | No | bool | Sets a chat to the continuous mode. When unset, leaves the mode unchanged. |
Response
| Field | Data type | Notes |
|---|---|---|
thread_id | string | |
event_ids | []string | Returned only when the chat was resumed with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.3/customer/action/resume_chat?license_id=<license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat": {
"id": "PWLW03ICW7"
}
}'
Response
Copied!
{
"thread_id": "Z8AGR5OUW"
}
Deactivate Chat
Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/deactivate_chat |
| RTM API equivalent | deactivate_chat |
| Webhook | incoming_event and chat_deactivated |
Request
| Parameter | Required | Data type | |
|---|---|---|---|
id | Yes | string |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/deactivate_chat?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"id": "PWLW03ICW7"
}'
Configuration
Get Dynamic Configuration
Returns the dynamic configuration of a given group. It provides data to call Get Configuration and Get Localization.
Specifics
| HTTP Method | GET |
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_dynamic_configuration |
| RTM API equivalent | - |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
group_id | No | number | The ID of the group that you want to get a dynamic configuration for. ID of the default group is used if not provided. |
url | No | string | The URL that you want to get a dynamic configuration for. |
channel_type | No | string | The channel type that you want to get a dynamic configuration for. |
test | No | bool | Treats a dynamic configuration request as a test. |
Response
| Field | Data type | Notes |
|---|---|---|
group_id | number | The ID of the group for which the dynamic configuration is returned. |
client_limit_exceeded | bool | Specifies if the limit of customers having a chat was exceeded. |
domain_allowed | bool | Specifies if url is configured as a trusted domain (configurable in the Agent Application). |
config_version | string | The version for which you want to get a configuration. Use it as version when calling Get Configuration. |
localization_version | string | The version for which you want to get a localization. Use it as version when calling Get Localization. |
language | string | The language of the group for which the dynamic configuration is returned. |
REQUESTCopied!
curl -X GET \
'https://api.livechatinc.com/v3.3/customer/action/get_dynamic_configuration?license_id=<license_id>&group_id=0'
Response
Copied!
{
"group_id": 0,
"client_limit_exceeded": false,
"domain_allowed": true,
"config_version": "84cc87cxza5ee24ed0f84fe3027fjf0c71",
"localization_version": "79cc87cea5ee24ed0f84fe3027fc0c74",
"language": "en"
}
Get Configuration
Returns the configuration of a given group in a given version. Contains data based on which the Chat Widget can be built.
Specifics
| HTTP Method | GET |
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_configuration |
| RTM API equivalent | - |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
group_id | Yes | number | The ID of the group that you want to get a configuration for. |
version | Yes | string | The version that you want to get a configuration for. Returned from Get Dynamic Configuration as the config_version parameter. |
REQUESTCopied!
curl -X GET \
'https://api.livechatinc.com/v3.3/customer/action/get_configuration?license_id=<license_id>&group_id=0&version=84cc87cxza5ee24ed0f84fe3027fjf0c71'
Response
Copied!
{
"buttons": [
{
"id": "0466ba53cb",
"type": "image",
"online_value": "livechat.s3.amazonaws.com/default/buttons/button_online007.png",
"offline_value": "livechat.s3.amazonaws.com/default/buttons/button_offline007.png"
},
{
"id": "08ca886ba8",
"type": "image",
"online_value": "livechat.s3.amazonaws.com/default/buttons/button_online003.png",
"offline_value": "livechat.s3.amazonaws.com/default/buttons/button_offline003.png"
},
{
"id": "3344e63cad",
"type": "text",
"online_value": "Live chat now",
"offline_value": "Leave us a message"
}
],
"ticket_form": {
// "Form" object
}, // optional
"prechat_form": {
// "Form" object
}, // optional
"integrations": {},
"properties": {
"group": {},
"license": {}
}
}
Events
Send Event
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.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/send_event |
| RTM API equivalent | send_event |
| Webhook | incoming_event |
Request
| Parameter | 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 | 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. |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/send_event?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PWLW03ICW7",
"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.3/customer/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.3/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
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.3/customer/action/send_rich_message_postback |
| 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 or false |
thread_id | Yes | string |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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
}
}'
Send Sneak Peek
Sends a sneak peek to a chat.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/send_sneak_peek |
| RTM API equivalent | send_sneak_peek |
| Webhook | - |
Request
| 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 |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}'
Localization
Get Localization
Returns the localization of a given language and group in a given version. Contains translated phrases for the Chat Widget.
Specifics
| HTTP Method | GET |
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_localization |
| RTM API equivalent | - |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
group_id | Yes | number | The ID of the group that you want to get a localization for. |
language | Yes | string | The language that you want to get a localization for. |
version | Yes | string | The version that you want to get a localization for. Returned from Get Dynamic Configuration as the localization_version parameter. |
REQUESTCopied!
curl -X GET \
'https://api.livechatinc.com/v3.3/customer/action/get_localization?license_id=<license_id>&group_id=0&language=en&version=79cc87cea5ee24ed0f84fe3027fc0c74'
Response
Copied!
{
"Agents_currently_not_available": "Our agents are not available at the moment.",
"Agents_not_available": "Our agents are not available at the moment.",
"Agents_not_available_continuous": "Our agents are not available right now, but you can still send messages. We'll notify you at your email address when you get a reply.",
"Assistly_ticket_created": "A support ticket has been created for your case.",
"Assistly_ticket_notification": "You will be emailed at %email% when it's resolved.",
...
}
Properties
Update Chat Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/update_chat_properties |
| RTM API equivalent | update_chat_properties |
| Webhook | chat_properties_updated |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
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. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/update_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"id": "Q1GZ3FNAT9",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "Chat property value updated by Customer"
}
}
}'
Delete Chat Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/delete_chat_properties |
| RTM API equivalent | delete_chat_properties |
| Webhook | chat_properties_deleted |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
id | Yes | string | Id of the chat you want to delete properties of. |
properties | Yes | object | Chat properties to delete. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/delete_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"id": "Q1GZ3FNAT9",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
}'
Update Thread Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/update_thread_properties |
| RTM API equivalent | update_thread_properties |
| Webhook | thread_properties_updated |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat_id | Yes | string | Id of the chat you want to set properties for. |
thread_id | Yes | string | Id of the thread you want to set properties for. |
properties | Yes | object | Chat properties to set. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}
}
}'
Delete Thread Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/delete_thread_properties |
| RTM API equivalent | delete_thread_properties |
| Webhook | thread_properties_deleted |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
chat_id | Yes | string | Id of the chat you want to delete 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. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
]
}
}'
Update Event Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/update_event_properties |
| 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.3/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"
}
}
}'
Delete Event Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/delete_event_properties |
| 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. 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.3/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"
]
}
}'
List License Properties
Returns the properties of a given license. It only returns the properties a Customer has access to.
Specifics
| HTTP Method | GET |
| Method URL | https://api.livechatinc.com/v3.3/customer/action/list_license_properties |
| RTM API equivalent | - |
| Webhook | - |
Request
| Query string parameter | Required | Data type | Notes |
|---|---|---|---|
namespace | No | string | Property namespace to retrieve |
name | No | string | Property name |
REQUESTCopied!
curl -X GET \
'https://api.livechatinc.com/v3.3/customer/action/list_license_properties?license_id=123&namespace=0805e283233042b37f460ed8fbf22160&name=string_property' \
-H 'Content-Type: application/json'
Response
Copied!
{
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
List Group Properties
Returns the properties of a given group. It only returns the properties a Customer has access to.
Specifics
| HTTP Method | GET |
| Method URL | https://api.livechatinc.com/v3.3/customer/action/list_group_properties |
| RTM API equivalent | - |
| Webhook | - |
Request
| Query string parameter | Required | Data type | Notes |
|---|---|---|---|
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 |
REQUESTCopied!
curl -X GET \
'https://api.livechatinc.com/v3.3/customer/action/list_group_properties?license_id=11069052&id=1&namespace=0805e283233042b37f460ed8fbf22160&name=string_property' \
-H 'Content-Type: application/json'
Response
Copied!
{
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
Customers
Update Customer
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/update_customer |
| RTM API equivalent | update_customer |
| Webhook | customer_session_fields_updated * |
* The webhook will be sent only if the customer has active chats.
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
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.
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}]
}'
Set Customer Session Fields
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/set_customer_session_fields |
| RTM API equivalent | set_customer_session_fields |
| Webhook | customer_session_fields_updated * |
* The webhook will be sent only if the customer has active chats.
Request
| 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.
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}]
}'
Get Customer
Returns the info about the Customer requesting it.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_customer |
| RTM API equivalent | get_customer |
| Webhook | - |
Response
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. |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/get_customer?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
Response
Copied!
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"type": "customer",
"name": "Thomas Anderson", // optional
"email": "t.anderson@example.com", // optional
"avatar": "https://example.com/avatars/1.jpg", // optional
"session_fields": [{ // optional
"custom_key": "custom_value"
}, {
"another_custom_key": "another_custom_value"
}]
}
Status
List Group Statuses
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/list_group_statuses |
| RTM API equivalent | list_group_statuses |
| Webhook | - |
Request
| 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.
Response
No response payload (200 OK).
Response
Group Not Found | If you send group_id of a group that doesn't exists, the id won't be included in the resposne. |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/list_group_statuses?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"all": true
}'
Response
Copied!
{
"groups_status": {
//1,2,3 are group ids, online/offline/online_for_queue are statuses of the groups
1: "online",
2: "offline",
3: "online_for_queue"
}
}
Other
Check Goals
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.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/check_goals |
| RTM API equivalent | - |
| Webhook | - |
Request
| 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 |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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
}'
Get Form
Returns an empty ticket form of a prechat or postchat survey.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_form |
| RTM API equivalent | get_form |
| Webhook | - |
Request
| 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 |
Response
enabled | If enabled: false, the form object is not returned. Prechat/postchat survey can disabled in the LiveChat Agent App UI. |
form | The Form data structure. |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}'
Response
Copied!
{
"form": {
// "Form" object
},
"enabled": true
}
Get Predicted Agent
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.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_predicted_agent |
| RTM API equivalent | get_predicted_agent |
| Webhook | - |
Response
| Field | Data type | Notes |
|---|---|---|
queue | bool | If true, the chat will be queued. |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/get_predicted_agent?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}'
Response
Copied!
{
"agent": {
"id": "b5657aff34dd32e198160d54666df9d8",
"name": "Agent Smith",
"avatar": "https://example.avatar/example.com",
"is_bot": false,
"job_title": "support hero",
"type": "agent"
},
"queue": false
}
Get URL Info
It returns the info on a given URL.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/get_url_info |
| RTM API equivalent | get_url_info |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
url | Yes | string | Valid website URL |
Response
| Field | 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 |
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}'
Response
Copied!
{
"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"
}
Mark Events As Seen
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/mark_events_as_seen |
| 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.3/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"
}'
Accept Greeting
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.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/accept_greeting |
| RTM API equivalent | accept_greeting |
| Webhook | - |
Request
| 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. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/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"
}'
Cancel Greeting
Cancels a greeting (an invitation to the chat). For example, Customers could cancel greetings by minimalizing the chat widget with a greeting.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/cancel_greeting |
| RTM API equivalent | cancel_greeting |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
unique_id | Yes | string | ID of the greeting to cancel. You can get it from the incoming_greeting push. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/cancel_greeting?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"unique_id": "Q10X0W041P"
}'
Request Email Verification
Requests the verification of the customer's email address by sending them a verification email with the identity confirmation link.
Once the customer verifies their identity, we'll send a POST callback to the URL you provided in the callback_uri request parameter. The callback will contain the verified email in the payload.
The identity verification mechanism has the following constraints:
- We'll store multiple verification requests until a customer confirms their identity. Once the identity is confirmed, we'll send a callback only for the 10 most recent verification requests, not for all stored requests.
- Seven days after the last verification request, all callbacks are voided and, as a result, won't be sent.
- If a customer has already verified their email, the callback will be sent immediately, without prompting the customer to verify it again.
Specifics
| Method URL | https://api.livechatinc.com/v3.3/customer/action/request_email_verification |
| RTM API equivalent | - |
| Webhook | - |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
callback_uri | Yes | string | URI to be called after the customer confirms their email address. Should return 200 code. There are no retries. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
'https://api.livechatinc.com/v3.3/customer/action/request_email_verification?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"callback_uri": "http://example.com"
}'
Webhooks
Here's what you need to know about webhooks:
- Webhooks notify you when specific events are triggered.
- They can be generated by both Web and RTM API actions.
- When using RTM API, you can be also notified about events with pushes.
- Webhooks and pushes have similar payloads.
- There's a limit of three weebhoks for every action a Client ID can register.
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. |
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. |
service_unavailable | Not accepting new requests | New requests are temporarily not being accepted. |
too_many_requests | Too many requests | The request's rate limit was exceeded. It'll be unblocked automatically after some time. |
unsupported_version | 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!