Web API Reference

4 minutes reading time

Introduction

Versioning

This document describes the Customer Chat Web API v3.1. 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 by 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.

Postman Collection

You can find all the requests from the Customer Chat Web API v3.1 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace the sample token with your own.

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
Filled form
Message
Rich message
Custom
System message

File

The File event informs about a file being uploaded.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the LiveChat CDN. It's recommended to use the URL returned by `upload_file`.

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

Sample File in response

Copied!

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "file",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "properties": {
    // "Properties" object
  },
  "name": "image25.png", // generated server-side
  "url": "https://example.com/image25.png",
  "thumbnail_url": "https://example.com/thumbnail.png", // generated server-side
  "thumbnail2x_url": "https://example.com/thumbnail2x.png", // generated server-side
  "content_type": "image/png", // generated server-side
  "size": 123444, // generated server-side
  "width": 640, // generated server-side
  "height": 480 // generated server-side
}

Filled form

The 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`
`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`	always
`properties`	optionally
`form_id`	always
`fields`	always	An array of form fields

Sample Filled form in response

Copied!

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",  // generated server-side
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
	"properties": {
		// "Properties" object
	},
	"form_id": "1473433500211",
	"fields": [{
		"type": "name",
		"id": "154417206262603539",
		"label": "Your name",
		"answer": "John Doe"
	}, {
		"type": "email",
		"id": "154417206262601584",
		"label": "Your email",
		"answer": "customer1@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": {
			"group_id": 1,
			"label": "Marketing"
		}
	}]
}

Message

Message event contains text message to other chat users.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`
`text`	yes	`string`	Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
`type`	yes	`string`	`message`
`properties`	no	`object`	Properties
`postback`	no	`object`	Indicates that the message event was generated in response to a rich message event.
`postback.id`	yes	`string`	ID of the postback from the rich message event.
`postback.thread_id`	yes	`string`	ID of the thread with the rich message event.
`postback.event_id`	yes	`string`	ID of the rich message event.
`postback.type`	no	`string`	Should be used together with `postback.value` (when one of them is present, the other is required).
`postback.value`	no	`string`	Should be used together with `postback.type` (when one of them is present, the other is required).

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", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "properties": {
    // "Properties" object
  }
}

Rich message

Rich message (RM) event contains a rich message data structure. Read more about rich messages.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`	You can give your RM a custom ID.
`type`	yes	`string`	Event type: `rich_message`
`properties`	no	`object`	The properties data structure
`template_id`	yes	`string`	Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`.
`elements`	no	`array`	Can contain up to 10 `element` objects.
`elements.title`	yes	`string`	Displays formatted text on RMs.
`elements.subtitle`	yes	`string`	Displays formatted text on RMs.
`elements.image`	yes	`image`	Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`.
`elements.buttons`	no	`array`	Displays buttons. Can contain up to 11 `button` objects.
`elements.buttons.text`	yes	`string`	Text displayed on a button.
`elements.buttons.type`	yes	`array`	Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`. More...
`elements.buttons.value`	yes	`string`	Should be used together with `elements.buttons.type`.
`elements.buttons.webview_height`	yes	`string`	Required only for the `webview` 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`.

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

Sample Rich message event

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": {
    // "Properties" object
  },
  "template_id": "cards",
  "elements": [
    {
      "title": "Lorem ipsum dolor.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "image": {
        "name": "image25.png",
        "url": "https://example.com/image25.png",
        "content_type": "image/png",
        "size": 123444,
        "width": 640,
        "height": 480
      },
      "buttons": [
        {
          "text": "yes",
          "postback_id": "action_yes",
          "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
        },
        {
          "text": "no",
          "postback_id": "action_no",
          "user_ids": []
        },
        {
          "type": "phone",
          "text": "value",
          "value": "790034890",
          "webview_height": "tall",
          "postback_id": "action_call",
          "user_ids": []
        }
      ]
    }
  ]
}

Custom

Custom event is an event with customizable payload.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`	You can give the event a custom ID.
`type`	yes	`string`	Event type: `custom`
`content`	no	`object`	The content you define
`properties`	no	`object`	The properties data structure

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

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": {
    // "Properties" object
  }
}

System message

System message event is a native system event sent in specific situations.

Request

Field	Required	Data type	Notes
`custom_id`	no	`string`	You can give the system message a custom ID.
`type`	yes	`string`	`system_message`
`text`	no	`string`	Text displayed to recipients
`system_message_type`	yes	`string`	System message type
`text_vars`	no	`object`	Variables used in the text

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 event

Copied!

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "system_message",
  "text": "hello there",
  "system_message_type": "routing.assigned",
  "text_vars": {
    "agent": "John Doe"
  }
}

Available system messages

Here's the list of all system messages you might come across:


`agent_added` `agent_removed` `archived_customer_disconnected` `chat_transferred` `customer_added` `customer_banned` `customer_removed` `manual_archived_agent` `manual_archived_customer` `rating.chat_commented` `rating.chat_rated`	`rating.chat_rating_canceled` `routing.archived_deleted` `routing.archived_disconnected` `routing.archived_inactive` `routing.archived_offline` `routing.archived_other` `routing.archived_remotely_signed_out` `routing.archived_signed_out` `routing.assigned_deleted` `routing.assigned_disconnected` `routing.assigned_inactive`	`routing.assigned_other` `routing.assigned_remotely_signed_out` `routing.assigned_signed_out` `routing.unassigned_deleted` `routing.unassigned_disconnected` `routing.unassigned_other` `routing.unassigned_remotely_signed_out` `routing.unassigned_signed_out` `system_archived` `transcript_requested` `transcript_sent`

`agent_added`

Content	Generated when
%initiator% added %agent% to the chat	Agent was added to chat via the `add_user_to_chat` request and is not the first Agent in that chat.

`agent_removed`

Content	Generated when
%initiator% removed %agent% from the chat	Agent was removed from chat via the `remove_user_from_chat` request.

`archived_customer_disconnected`

Content	Generated when
%customer% left the chat	Chat ended after Customer left the website.

`chat_transferred`

Content	Generated when
%initiator% transferred the chat to %targets%	Chat was transferred via the `transfer_chat` request.

`customer_added`

Content	Generated when
%initiator% added %customer% to the chat	Customer was added to chat via the `add_user_to_chat` request.

`customer_banned`

Content	Generated when
Chat archived because customer was banned by %agent% for %duration% day(s)	Chat ended becaus Customer was banned via the `ban_customer` request.

`customer_removed`

Content	Generated when
%initiator% removed %customer% from the chat	Customer was removed from chat via the `remove_user_from_chat` request.

`manual_archived_agent`

Content	Generated when
%agent% archived the chat	Agent closed chat via the `close_thread` request.

`manual_archived_customer`

Content	Generated when
%customer% archived the chat	Customer closed chat via the `close_thread` request.

`rating.chat_commented`

Content	Generated when
%customer% left the following comment: %comment%	Chat was commented by Customer.

`rating.chat_rated`

Content	Generated when
%customer% rated the chat as %score%	Chat was rated by Customer.

`rating.chat_rating_canceled`

Content	Generated when
%customer% canceled the chat rating	Chat rating was cancelled by Customer.

`routing.archived_deleted`

Content	Generated when
The chat was closed because %agent% account had been deleted	Chat was archived after Agent was removed from the license. No other Agent could be selected, and queues were disabled.

`routing.archived_disconnected`

Content	Generated when
The chat was closed because %agent% had lost internet connection	Chat was archived after Agent unexpectedly lost connection. No other Agent could be selected, and queues were disabled.

`routing.archived_inactive`

Content	Generated when
Chat archived due to %duration% minutes of inactivity	No new messages were posted for an extended amount of time.

`routing.archived_offline`

Content	Generated when
Chat archived due to no available agents	No Agent could be selected after chat was placed in the queue.

`routing.archived_other`

Content	Generated when
The chat was closed	Chat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

`routing.archived_remotely_signed_out`

Content	Generated when
The chat was closed because %agent% had been remotely signed out	Chat was archived after an Agent was logged out. No other Agent could be selected and queues were disabled.

`routing.archived_signed_out`

Content	Generated when
The chat was closed because %agent% had signed out	Chat was archived after Agent logged out. No other Agent could be selected, and queues were disabled.

`routing.assigned_deleted`

Content	Generated when
Chat assigned to %agent_added% because %agent_removed% account had been deleted	Chat was assigned to a new Agent after the previous one was removed from the license.

`routing.assigned_disconnected`

Content	Generated when
Chat assigned to %agent_added% because %agent_removed% had lost internet connection	Chat was assigned to a new Agent after the previous one unexpectedly lost connection.

`routing.assigned_inactive`

Content	Generated when
Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutes	Chat was assigned to a new Agent after the previous one failed to response in a timely manner.

`routing.assigned_other`

Content	Generated when
The chat was closed	Chat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

`routing.assigned_remotely_signed_out`

Content	Generated when
Chat assigned to %agent_added% because %agent_removed% had been remotely signed out	Chat was assigned to a new Agent after the previous one was logged out.

`routing.assigned_signed_out`

Content	Generated when
Chat assigned to %agent_added% because %agent_removed% had signed out	Chat was assigned to a new Agent after the previous one logged out.

`routing.unassigned_deleted`

Content	Generated when
Customer was queued because %agent% account has been deleted	Chat was queued after Agent was removed from the license.

`routing.unassigned_disconnected`

Content	Generated when
Customer was queued because %agent% had lost internet connection	Chat was queued after Agent unexpectedly lost connection.

`routing.unassigned_other`

Content	Generated when
Chat is unassigned	Chat was queued after Agent was removed from chat for other reasons.

`routing.unassigned_remotely_signed_out`

Content	Generated when
Customer was queued because %agent% had been remotely signed out	Chat was queued after Agent was logged out.

`routing.unassigned_signed_out`

Content	Generated when
Customer was queued because %agent% had signed out	Chat was queued after Agent logged out.

`system_archived`

Content	Generated when
Chat archived	License was moved to another lc_serv instance while there were still active chats.

`transcript_requested`

Content	Generated when
%customer% requested the chat transcript to be sent to %email%	Customer enables transcript.

Users

Users are another important data structure. Within this data structure type, we can distinguish:

Customer
Agent

Customer

Sample Customer data structure

Copied!

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "https://example.com/avatars/1.jpg",
  "fields": {
    "custom field name": "custom field value"
  },
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}

Field	Req./Opt.
`avatar`	optional
`email`	optional
`name`	optional
`fields`	optional

Agent

Sample Agent data structure

Copied!

{
  "id": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "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
Chats
Chat summaries
Form fields
Properties
Threads

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",
  "users": [
    // array of "User" objects
  ],
  "threads": [
    // optional
    // "Thread" object
  ],
  "threads_summary": [
    {
      "thread_id": "K600PKZON8",
      "order": 129846129847
    },
    {
      "thread_id": "K600PKZON8",
      "order": 129846129848
    }
  ],
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": true
}

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_thread_summary and last_event_per_type.

Sample Chat summary data structure

Copied!

{
  "id": "PJ0MRSHTDG",
  "users": [
    // array of "User" objects
  ],
  "last_event_per_type": {
    // last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_order": 3,
      "event": {
        // "restricted_access": true
        // or
        // "Event > Message" object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON6",
      "thread_order": 1,
      "event": {
        // "restricted_access": true
        // or
        // "Event > System message" object
      }
    }
    // ...
  },
  "last_thread_summary": {
    "id": "K600PKZON8",
    "order": 3,
    "timestamp": 1473433500,
    "user_ids": ["agent1@example.com"],
    "properites": {
      // "Properites" object
    },
    "tags": ["bug_report"]
  },
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": false
}

Form fields

A component of the Filled form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types
`answer`	yes	`any`	For all field types
`answer.id`	yes	`string`	Answer id; for all field types
`answer.label`	yes	`string`	Answer label; for all field types
`answer.group_id`	yes	`number`	For `group_chooser`

Response

Copied!

{
	"fields": [{
		"type": "name",
		"id": "154417206262603539",
		"label": "Your name",
		"answer": "John Doe"
	}, {
		"type": "email",
		"id": "154417206262601584",
		"label": "Your email",
		"answer": "customer1@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": {
			"group_id": 1,
			"label": "Marketing"
		}
	}]
}

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": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure

Copied!

{
  "id": "K600PKZON8",
  "timestamp": 1473433500,
  "active": true,
  "user_ids": ["agent1@example.com"],
  "restricted_access": true,
  "events": [
    // array of "Event" objects
  ],
  "order": 112057129857,
  "properties": {
    // "Properties" object
  },
  "access": {
    // "Access" object
  }
}

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 `true`.
`properties`	optional	-
`restricted_access`	optional	-

Methods

Web API actions can generate webhooks, as well as pushes. However, pushes can be delivered only in the websocket transport. If you want to be notified about emitted events with webhooks, you need to register them first.

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

Header	Value	Notes
`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. Read more...
`X-Region`	`fra`	Required for a license from Europe. More info...
`X-API-Version`	API version, for example `3.1`	You don't need this header if you specify API version in the URL.

Every request to Customer Chat API needs to have the following query string parameters:

Required parameter	Data type	Notes
`license_id`	`integer`	LiveChat account ID

REQUEST

Copied!

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

Available methods


Chats	`get_chats_summary` `get_chat_threads_summary` `get_chat_threads` `start_chat` `activate_chat` `close_thread`
Events	`send_event` `upload_file` `send_rich_message_postback` `send_sneak_peek`
Properties	`update_chat_properties` `delete_chat_properties` `update_chat_thread_properties` `delete_chat_thread_properties` `update_event_properties` `delete_event_properties`
Customers	`update_customer` `set_customer_fields`
Status	`get_groups_status`
Other	`check_goals` `get_form` `get_predicted_agent` `get_url_details` `mark_events_as_seen`

Chats

Get Chats Summary

It returns summaries of the chats a Customer participated in.


Method URL	`https://api.livechatinc.com/v3.1/customer/action/get_chats_summary`
RTM API equivalent	`get_chats_summary`
Webhook	-

Parameter	Required	Type	Notes
`offset`	No	`number`	Default: 0, maximum: 100
`limit`	No	`number`	Default: 10, maximum: 25

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`offset`	No	`number`	Default: 0
`limit`	No	`number`	Default: 25, maximum: 100

Parameters	Required	Data type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`	Initial chat properties
`chat.access`	No	`object`	Chat access to set; default: all agents.
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array
`chat.thread.properties`	No	`object`	Initial chat thread properties
`continuous`	No	`bool`	Starts chat as continuous (online group is not required); default: `false`.

Parameter	Data type	Notes
`chat_id`	`string`
`thread_id`	`string`
`event_ids`	`[]string`	Returned only when the chat was started with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.

Request object	Required	Type	Notes
`chat`	Yes	`object`
`chat.id`	Yes	`string`	ID of the chat that will be activated.
`chat.access`	No	`object`	Chat access to set; default: all agents.
`chat.properties`	No	`object`	Initial chat properties
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array
`chat.thread.properties`	No	`object`	Initial chat thread properties
`continuous`	No	`bool`	Sets a chat to the continuous mode. When unset, leaves the mode unchanged.

Parameters	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat that you to send a message to.
`event`	Yes	`object`	The event object
`attach_to_last_thread`	No	`bool`	If `true`, adds an event to last (inactive) thread. Otherwise, it doesn't creates a new one; default: `false`.

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
`chat_id`	Yes	`string`	Id of the chat you to set a property for.
`properties`	Yes	`object`	Chat properties to set. You should stick to the general properties format and include namespace, property name and value.

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`	Id of the chat you want to delete properties of.
`properties`	Yes	`object`	Chat properties to delete.

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`	Chat thread properties to delete.

Parameter	Required	Data type	Notes
`all`	No	`bool`	If set to `true`, you will get statuses of all the groups.
`groups`	No	`array`	A table of groups' IDs

Parameter	Required	Data type	Notes
`customer_fields`	Yes	`object`	`key:value` format
`group_id`	Yes	`number`
`page_url`	Yes	`string`

Parameter	Required	Data type	Notes
`group_id`	Yes	`number`	Id of the group from which you want the form.
`type`	Yes	`string`	Form type; possible values: `prechat` or `postchat`

Parameter	Notes
`enabled`	If `enabled: false`, the `form` object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI.
`header`	For headers; the field has no `answer`, therefore is not sent in the Filled form event.
`rating`	For rating; the field has no `answer`, therefore is not sent in the Filled form event.

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

Type	Default Message	Notes
`authentication`	Authentication error	An invalid or expired access token.
`authorization`	Authorization error	Agent 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. It returns the correct `region` in the optional `data` object.
`validation`	Wrong format of request
`request_timeout`	Request timed out	Timeout threshold is 15 seconds.
`unsupported_version`	Unsupported version	Unsupported protocol version.
`wrong_product_version`	Wrong product version	License is not LiveChat 3 (probably still LiveChat 2).

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