Web API Reference

Introduction

Versioning

This document describes the Agent Chat Web API v3.3, which is a legacy version. For production-ready applications, it's best to use to the current stable version. Read more about versioning...

Lifecycle headers

API responses will contain one of two headers related to the API lifecycle: Legacy or Deprecation. These headers specify when the associated stage ends (in the YYYY-MM-DD format).

What is Web API

Web API is similar to REST API. Client can send a request message that results in getting a response message. It's also possible to get webhooks.

When to use Web API

If you're wondering which API to use - Agent Chat RTM API or Web API, keep on reading.

Web API allows for building stateless integrations. The communication is done via XHR requests. The implementation is easier than with RTM API, but you need to take possible time delays into consideration.

Not what you're looking for? Perhaps, you need to use Agent Chat RTM API instead.

Access

The basics on authorization, access tokens, and scopes in the Agent Chat Web API.

Authorization

Agent authorization is handled with access tokens. Find out how to get an access token from Agent authorization flows. Take note you won't be able to use this token for the Customer Chat API.

Scopes

All authorization scopes are listed in the Scopes document. If a method requires certain scopes, you'll find them included in the method description. Keep in mind that Web API requires authorization every time you make a request.

Data centers

LiveChat system operates in two data centers: dal (USA) and fra (Europe). The default data center is dal.

All the LiveChat OAuth 2.1 access tokens have a prefix: dal: or fra:. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.

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

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

Rate limits

To prevent sending a massive number of requests, there are rate limits for method calls. After exceeding those limits, the requester will get a Too many requests error in the response of a specific request. After some time, the request will be unblocked so it can be sent again.

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

Data structures

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

Methods

HTTP method	The API endpoint
`POST`	`https://api.livechatinc.com/v3.3/agent/action/<action>`

If you specify the API version in the URL, you don't have to include the optional "X-API-Version: 3.3" header.

Required Header	Value	Notes
`Content-Type`	`multipart/form-data; boundary=<boundary>`	Valid for the `upload_file` method
`Content-Type`	`application/json`	Valid for all methods except for `upload_file`
`Authorization`	`Bearer <token>`	Access token
`X-Author-Id`	`<bot_agent_id>`	Valid only for Bot Agents

GENERAL WEB API REQUEST FORMAT

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/<action> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    // payload
    }'

Available methods


Chats	`list_chats` `list_threads` `get_chat` `list_archives` `start_chat` `resume_chat` `deactivate_chat` `follow_chat` `unfollow_chat`
Chat access	`grant_chat_access` `revoke_chat_access` `transfer_chat`
Chat users	`add_user_to_chat` `remove_user_from_chat`
Events	`send_event` `upload_file` `send_rich_message_postback`
Properties	`update_chat_properties` `delete_chat_properties` `update_thread_properties` `delete_thread_properties` `update_event_properties` `delete_event_properties`
Thread tags	`tag_thread` `untag_thread`
Customers	`get_customer` `list_customers` `create_customer` `update_customer` `ban_customer` `follow_customer` `unfollow_customer`
Status	`set_routing_status` `list_routing_statuses`
Other	`mark_events_as_seen` `send_typing_indicator` `multicast` `list_agents_for_transfer`

Chats

List Chats

It returns summaries of the chats an Agent has access to.


Method URL	`https://api.livechatinc.com/v3.3/agent/action/list_chats`
Required scopes	`chats--all:ro` `chats--access:ro` `chats--my:ro`
RTM API equivalent	`list_chats`
Webhook	-

Parameter	Required	Type	Notes
`filters`	No	`object`	When paginating, `filters` provided in the first request are remembered and automatically used for the subsequent requests. Providing a new `filters` object will result in a `validation` error. To reset the filters, start paginating with a new set of filters.
`filters.include_active`	No	`bool`	Defines if the returned chat summary includes active chats; default: `true`.
`filters.include_chats_without_threads`	No	`bool`	Defines if the returned chat summary includes chats without any threads; default: `true`.
`filters.group_ids`	No	`array`	Array of group IDs. Max array size: 200
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`
`sort_order`	No	`string`	Possible values: `asc` - oldest chats firstm `desc` - newest chats first (default)
`limit`	No	`number`	Default: 10, maximum: 100
`page_id`	No	`string`

Field	Data type	Notes
`chats_summary`	`array`	An array of Chat summary data structures
`next_page_id`	`string`	In relation to `page_id` specified in the request. Appears in the response only when there's a next page.
`previous_page_id`	`string`	In relation to `page_id` specified in the request Appears in the response only when there's a previous page.
`found_chats`	`number`	An estimated number. The real number of found chats can slightly differ.

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.
`filters`	No	`object`
`filters.from`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.to`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`

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

Parameter	Required	Data type	Notes
`filters`	No	`object`
`filters.query`	No	`string`
`filters.from`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.to`	No	`string`	Date & time format with a resolution of microseconds, UTC string, `YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM`
`filters.thread_ids`	No	`array`	Array of thread IDs. Cannot be used with other filters or pagination; max array size: 20.
`filters.group_ids`	No	`array`	Array of group IDs. Max array size: 200
`filters.properties.<namespace>.<name>.<filter_type>`	No	`any`	* described below
`filters.agents.<filter_type>`	No	`any`	`exists` set to `false` will return unassigned chats; `true` will return the assigned ones.
`filters.tags.<filter_type>`	No	`any`
`filters.sales.<filter_type>`	No	`any`
`filters.goals.<filter_type>`	No	`any`
`filters.surveys.<survey>`	No	`array`	described below**
`filters.events.types`	No	`array`	Array of Event types. Duplicates are ignored.
`page_id`	No	`string`
`sort_order` *******	No	`string`	Default: `desc`
`limit`	No	`number`	Default: 10, min: 1, max: 100
`highlights`	No	`object`	Use it to highlight the match of `filters.query`. To enable highlights with default parameters, pass an empty object.
`highlights.pre_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `<em>`. Use it together with `highlights.post_tag`.
`highlights.post_tag`	No	`string`	An HTML tag to use for highlighting the matched text; default: `</em>`. Use it together with `highlights.pre_tag`.


Method URL	`https://api.livechatinc.com/v3.3/agent/action/start_chat`
Required scopes *	`chats.conversation--all:rw` `chats.conversation--access:rw` `chats.conversation--my:rw`
RTM API equivalent	`start_chat`
Webhook	`incoming_chat`

Parameters	Required	Data type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`
`chat.access`	No	`object`
`chat.users`	No	`[]object`	The list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	User ID
`chat.users.type`	Yes	`string`	`agent` or `customer`
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	The list of initial chat events object. Does not support the `form` type event in the LiveChat app.
`chat.thread.properties`	No	`object`
`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.users`	No	`[]object`	The list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	User ID
`chat.users.type`	Yes	`string`	`agent` or `customer`
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array
`chat.thread.properties`	No	`object`	Initial thread properties
`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.

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Chat Id
`access`	Yes	`object`
`access.type`	Yes	`string`	`group`
`access.id`	Yes	any

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible values: `agent` or `customer`
`require_active_thread`	No	`bool`	If `true`, it adds a user to a chat only if that chat has an active thread; default `false`.

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

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`event_id`	Yes	`string`
`postback`	Yes	`object`
`postback.id`	Yes	`string`	Postback name of the button
`postback.toggled`	Yes	`bool`	Postback toggled true/false
`thread_id`	Yes	`string`

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Id of the chat you to set properties for.
`properties`	Yes	`object`	Chat properties to set. You should stick to the general properties format and include namespace, property name and value.

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Id of the chat you want to delete property 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. You should stick to the general properties format and include namespace, property name and value.

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.

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to add a tag to.
`thread_id`	Yes	`string`	Id of the thread you want to add a tag to.
`tag`	Yes	`string`	Tag name. It's case sensitive.

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to remove a tag from.
`thread_id`	Yes	`string`	Id of the thread you want to remove a tag from.
`tag`	Yes	`string`	Tag name. It's case sensitive.

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

Web API Reference


Action	`get_customer`
Required scopes	`customers:ro`
RTM API equivalent	`get_customer`
Push message	-

Field	Data type	Notes
`id`	string	Customer's ID.
`type`	string	`customer`
`name`	string	Customer's name. Returned only if set.
`email`	string	Customer's email. Returned only if set.
`avatar`	string	Customer's avatar. Returned only if set.
`created_at`	string	Specifies when the customer's identity was created.
`session_fields`	[]object	An array of custom object-enclosed `key:value` pairs. Returned only if set. Available for the session duration.
`statistics`	object	Counters for started threads, opened pages, etc.
`last_visit`	object	Geolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once.
`chat_ids`	[]string	IDs of a customer's chats. Returned only if the customer had at least one chat.

Parameter	Required	Data type	Notes
`id`	Yes	`string`	UUID v4 format is required
`name`	No	`string`
`email`	No	`string`
`avatar`	No	`string`	URL of the Customer's avatar
`session_fields`	No	`[]object`	An array of custom object-enclosed `key:value` pairs. Respects the order of items.

Parameter	Required	Data type	Notes
`status`	Yes	`string`	For Agents: `accepting_chats` or `not_accepting_chats`; for Bot Agents: `accepting_chats`, `not_accepting_chats`, or `offline`
`agent_id`	No	`string`	If not specified, the requester's status will be updated.

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

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat that to send the typing indicator to.
`recipients`	No	`string`	Default: `all`; `agents`
`is_typing`	Yes	`bool`

Parameter	Required	Data type	Notes
`recipients`	Yes	`object`	*
`content`	Yes	`any`	A JSON message to be sent
`type`	No	`string`	Multicast message type

Error type	Default message	Description
`authentication`	Authentication error	An invalid or expired access token.
`authorization`	Authorization error	User is not allowed to perform the action.
`chat_inactive`	No active chat thread	An action that requires an active thread performed on a chat with no active threads.
`entity_too_large`	Upload limit exceeded (10MB).	Client's request is too large.
`internal`	Internal server error
`license_expired`	License expired	The end of license trial or subcription.
`license_not_found`	License not found	License with the specified ID doesn't exist.
`limit_reached`	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).