Web API Reference

Introduction

Versioning

This document describes the Customer Chat Web API v3.4. 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 that it's not the same token you would use 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 OAuth 2.1 access tokens have a prefix: dal: or fra:. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.

Summing up, if the user token starts with fra, you should add the X-Region: fra header. If the token starts with, dal: you don’t have to specify the header.

If you get the misdirected_request error, use the prefix returned in the error as the value of X-Region.

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.4 in Postman. In our collection, we use environment variables that store, for example, the access token. Importing the collection from the link below downloads the environment as well. Remember to replace sample tokens with your own.

Data structures

To find sample payloads of events, users, and other common structures such as chats or threads visit the Data structures document.

Methods

HTTP method	The API endpoint	Methods
POST	`https://api.livechatinc.com/v3.4/customer/action/<action>`	All except for List License Properties, List Group Properties, Dynamic Config, Config and Localization
GET	`https://api.livechatinc.com/v3.4/customer/action/<action>`	List License Properties, List Group Properties, Get Dynamic Configuration, Get Configuration and Get Localization

Header	Value	Notes
`X-API-Version`	`3.4`	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	Methods
`organization_id`	`string`	All

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.4/customer/action?organization_id=<organization_id> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    // payload
    }'

Available methods


Chats	`list_chats` `list_threads` `get_chat` `start_chat` `resume_chat` `deactivate_chat`
Configuration	`get_dynamic_configuration` `get_configuration`
Events	`send_event` `upload_file` `send_rich_message_postback` `send_sneak_peek`
Localization	`get_localization`
Properties	`update_chat_properties` `delete_chat_properties` `update_thread_properties` `delete_thread_properties` `update_event_properties` `delete_event_properties` `list_license_properties` `list_group_properties`
Customers	`update_customer` `set_customer_session_fields` `get_customer`
Status	`list_group_statuses`
Other	`check_goals` `get_form` `get_predicted_agent` `get_url_info` `mark_events_as_seen` `accept_greeting` `cancel_greeting` `request_email_verification`

Chats

List Chats

It returns summaries of the chats a Customer participated in.


Method URL	`https://api.livechatinc.com/v3.4/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`

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.

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.

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`thread_id`	No	`string`	Default: the latest thread (if exists)

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. Does not support the `form` type event in the LiveChat app.
`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`.

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.

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.


HTTP Method	GET
Method URL	`https://api.livechatinc.com/v3.4/customer/action/get_dynamic_configuration`
RTM API equivalent	-
Webhook	-

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.

Field	Data type	Notes
`group_id`	`number`	The ID of the group for which the dynamic configuration is returned.
`organization_id`	`string`	The ID of the organization 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.

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat that you to send a message to.
`event`	Yes	`object`	Event object. Does not support the `form` type event in the LiveChat app.
`attach_to_last_thread`	No	`bool`	The flag is ignored for active chats. For inactive chats: `true` – the event will be added to the last thread; `false` – the request will fail. Default: `false`.

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`

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

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.

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.

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.

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.

Query string parameter	Required	Data type	Notes
`namespace`	No	`string`	Property namespace to retrieve
`name`	No	`string`	Property name

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

Web API Reference.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

Web API Reference

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.


`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.

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

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`


`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.

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

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`seen_up_to`	Yes	`string`	RFC 3339 date-time format

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.

Error type	Default message	Description
`authentication`	Authentication error	An invalid or expired access token.
`authorization`	Authorization error	User is not allowed to perform the action.
`chat_anonymized`	Chat anonymized	The request couldn't be performed on an anonymized chat.
`chat_inactive`	No active chat thread	An action that requires an active thread performed on a chat with no active threads.
`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.
`limit_reached`	Resource limit reached	Resource cannot be created/modified because the change would exceed the limit
`misdirected_request`	Wrong region	Client's request should be performed to another region. The correct region is returned in the optional data object – this is 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).