Web API Reference

Introduction

Versioning

This document describes the Agent Chat Web API v3.4. This is the developer preview version that provides a preview of the upcoming changes to the API. It's not open to public use. However, if you want to test some features, contact us at developers@livechat.com or ask on the chat, and we'll give you access.

What is Web API

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

When to use Web API

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

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

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

Access

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

Authorization

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

Scopes

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

Data centers

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

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

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

Rate limits

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

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.

Events

One of the data structures are events. They are sent to a chat via the send_event method. Apart from events, there are also Properties, Users, and Other common data structures.

These are the available event types:

File

The File event informs about an uploaded file.

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the LiveChat CDN. It's recommended to use the URL returned by `upload_file`.
`alternative_text`	no	`string`	Only applicable to images

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

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`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`postback`	no	`object`	Indicates that the message event was generated in response to a rich message event.
`postback.id`	yes	`string`	ID of the postback from the rich message event.
`postback.thread_id`	yes	`string`	ID of the thread with the rich message event.
`postback.event_id`	yes	`string`	ID of the rich message event.
`postback.type`	no	`string`	Should be used together with `postback.value` (when one of them is present, the other is required).
`postback.value`	no	`string`	Should be used together with `postback.type` (when one of them is present, the other is required).

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give your RM a custom ID.
`type`	yes	`string`	Event type: `rich_message`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	The properties data structure
`template_id`	yes	`string`	Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`.
`elements`	no	`array`	Can contain up to 10 `element` objects.
`elements.title`	yes	`string`	Displays formatted text on RMs.
`elements.subtitle`	yes	`string`	Displays formatted text on RMs.
`elements.image`	yes	`image`	Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `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` button`type`. 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`.

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.
`visibility`	always
`properties`	optionally
`template_id`	always
`elements`	optionally
`elements.title`	always
`elements.subtitle`	always
`elements.image`	always
`elements.buttons`	optionally
`elements.buttons.text`	always
`elements.buttons.type`	always
`elements.buttons.value`	always
`elements.buttons.webview_height`	always	Unless button `type` is different than `webview`.
`elements.buttons.postback_id`	always
`elements.buttons.user_ids`	always
`elements.buttons.target`	optionally

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
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	The properties data structure

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
`visibility`	no	`string`	It can be specified when sending system messages via the Send Event method. Possible values: `all`, `agents`.
`text_vars`	no	`object`	Variables used in the text

Field	Req./Opt.	Notes
`routing_status`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string; the timestamp of the most recent event seen by the Agent—all the previous events are considered seen.

Field	Req./Opt.	Notes
`agent_last_event_created_at`	optional
`avatar`	optional
`customer_last_event_created_at`	optional
`created_at`	optional
`email`	optional
`email_verified`	optional	Specifies if the customer confirmed their email address. See Request Email Verification.
`session_fields`	optional	An array of custom object-enclosed `key:value` pairs. Expires along with the session.
`name`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string
`last_visit`	optional
`present`	optional
`statistics`	optional

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

Reqiured 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


Method URL	`https://api.livechatinc.com/v3.4/agent/action/list_chats`
Required scopes	`chats--all:ro` `chats--access: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`


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

Field	Req./Opt.	Note
`access`	optional
`active`	required	Possible values: `true` (thread is still active) or `false`(thread no longer active)
`events`	optional	Doesn't exists if `restricted_access` is present.
`properties`	optional
`restricted_access`	optional	Contains the reason for access restriction.
`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.
`previous_accessible_thread_id`	optional	Present only if there is a preceding thread accessible for the requester. Field present only in `list_archives`.
`next_accessible_thread_id`	optional	Present only if there is a following thread accessible for the requester. Field present only in `list_archives`.
`created_at`	required	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.


Chats	`list_chats` `list_threads` `get_chat` `list_archives` `start_chat` `resume_chat` `deactivate_chat` `follow_chat` `unfollow_chat`
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`

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>.<properties_filter_type>`	No	`any`	* described below
`filters.agents.<filter_type>`	No	`any`	** described below `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.event_types.<event_type_filter_type>`	No	`any`	****** described below**
`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`.

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.
`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`
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

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

.css-1plb8kr{color:inherit;-webkit-text-decoration:none;text-decoration:none;position:relative;}.css-1plb8kr:hover{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1plb8kr:hover:before{content:"#";position:absolute;font-weight:300;left:-1em;top:1px;opacity:0.3;}Introduction

Web API Reference

Introduction

Parameter	Required	Data ype	Notes
`id`	Yes	`string`	Chat ID
`target`	No	`object`	If missing, the chat will be transferred within the current group.
`target.type`	Yes	`string`	`group` or `agent`
`target.ids`	Yes	`array`	`group` or `agent` IDs array
`ignore_agents_availability`	No	`bool`	If `true`, allows the chat to be enqueued after the transfer. Otherwise, fails when unable to immediately assign any agent from the requested groups; default `false`.
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; default `false`.

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`user_id`	Yes	`string`
`user_type`	Yes	`string`	Possible values: `agent` or `customer`
`visibility`	Yes	`string`	Possible values: `all` or `agents`
`ignore_requester_presence`	No	`bool`	If `true`, the requester doesn't need to be present on the list of chat users; 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
`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

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