API version

Web API Reference

5 minutes reading time

Introduction

Versioning

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

Postman Collection

You can find all the requests from the Customer Chat Web API v3.2 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.

Run in Postman

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

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfile
propertiesnoobjectProperties
urlyesstringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
namealways
urlalways
thumbnail_url, thumbnail2x_urlonly for images
content_typealways
size, width, heightonly 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
}

Filled form

Filled form event contains data from a form (prechat or postchat survey).

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfilled_form
propertiesnoobjectProperties
form_idyesstring
fieldsyesarrayThe fields a form contains. See form fields for details.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
form_idalways
fieldsalwaysAn array of form fields
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

FieldRequiredData typeNotes
custom_idnostring
textyesstringMax. 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.
typeyesstringmessage
propertiesnoobjectProperties
postbacknoobjectIndicates that the message event was generated in response to a rich message event.
postback.idyesstringID of the postback from the rich message event.
postback.thread_idyesstringID of the thread with the rich message event.
postback.event_idyesstringID of the rich message event.
postback.typenostringShould be used together with postback.value (when one of them is present, the other is required).
postback.valuenostringShould be used together with postback.type (when one of them is present, the other is required).

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealwaysmessage
author_idalways
textalways
postbackoptionallyAppears in a message only when triggered by a rich message.
postback.idalways
postback.thread_idalways
postback.event_idalways
postback.typeoptionallyAppears only if postback.value is present.
postback.valueoptionallyAppears only if postback.type is present.
propertiesoptionallyProperties
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

FieldRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
propertiesnoobjectThe properties data structure
template_idyesstringDefines how every Rich Message will be presented. Values: cards, sticker, or quick_replies.
elementsnoarrayCan contain up to 10 element objects.
elements.titleyesstringDisplays formatted text on RMs.
elements.subtitleyesstringDisplays formatted text on RMs.
elements.imageyesimageDisplays images on RMs. Required param: url; Optional params: name, content_type, size, width, height.
elements.buttonsnoarrayDisplays buttons. Can contain up to 13 button objects.
elements.buttons.textyesstringText displayed on a button.
elements.buttons.typeyesarrayDefines 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.valueyesstringShould be used together with elements.buttons.type.
elements.buttons.webview_heightyesstringRequired only for the webview buttontype. Possible values: compact, full, tall.
elements.buttons.postback_idyesstringA description of the sent action. Describes the action sent via send_rich_message_postback. More...
elements.buttons.user_idsyesarrayDescribes users that sent the postback with "toggled": true.

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string. Generated server-side.
propertiesoptionally
template_idalways
elementsoptionally
elements.titlealways
elements.subtitlealways
elements.imagealways
elements.buttonsoptionally
elements.buttons.textalways
elements.buttons.typealways
elements.buttons.valuealways
elements.buttons.webview_heightalwaysUnless button type is different than webview.
elements.buttons.postback_idalways
elements.buttons.user_idsalways
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
			},
			"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

FieldRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
propertiesnoobjectThe properties data structure

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
contentoptionally
propertiesoptionally
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

FieldRequiredData typeNotes
custom_idnostringYou can give the system message a custom ID.
typeyesstringsystem_message
textnostringText displayed to recipients
system_message_typeyesstringSystem message type
text_varsnoobjectVariables used in the text

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
textoptionally
system_message_typealways
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",
	"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"
}
FieldReq./Opt.Notes
avataroptional
emailoptional
nameoptional
session_fieldsoptionalAn 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
		]
	}
}
FieldReq./Opt.Note
group_idsrequiredgroup 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"
		}
	}
}
FieldReq./Opt.Note
propertiesoptional
accessoptional

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
}

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"
			}
		}
	]
}
FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types
answeryesanyFor all field types
answer.idyesstringAn identifier of each option a Customer can choose. For all field types.
answer.labelyesstringAnswer label; for all field types
answer.group_idyesnumberFor 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"
}
FieldReq./Opt.Note
accessoptional
activerequiredPossible values: true (thread is still active) or false(thread no longer active).
eventsoptional
propertiesoptional
queueoptionalPresent only if the chat is in the queue. Wait time is approximated in seconds.
previous_thread_idoptionalPresent only if there is a preceding thread.
next_thread_idoptionalPresent only if there is a following thread.
created_atrequiredDate & time format with a resolution of microseconds, UTC string. Generated server-side.

Methods

HTTP methodThe API endpointMethods
POSThttps://api.livechatinc.com/v3.2/customer/action/<action>All except for Get License Properties and Get Group Properties
GEThttps://api.livechatinc.com/v3.2/customer/action/<action>Get License Properties and Get Group Properties
HeaderValueNotes
X-API-Version3.2Not needed if you sepcify the API version in the URL.
Content-Typemultipart/form-data; boundary=<boundary>Valid for the Upload File method
Content-Typeapplication/jsonValid for every method except for Upload File
AuthorizationBearer <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 parameterData typeNotesMethods
license_idintegerLiveChat account IDAll
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/customer/action?license_id=<license_id> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    // payload
    }'

Available methods

Run in Postman

Chats

List Chats

It returns summaries of the chats a Customer participated in.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/list_chats
RTM API equivalentlist_chats
Webhook-
Request
ParameterRequiredTypeNotes
limitNonumberDefault: 10, maximum: 25
sort_orderNostringPossible values: asc, desc (default). Chat summaries are sorted by the creation date of its last thread.
page_idNostring
Response
ParameterData typeNotes
total_chatsnumberAn estimated number. The real number of found chats can slightly differ.
next_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's the next page.
previous_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's the previous page.
chats_summaryarrayArray of Chat summary data structures.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/list_threads
RTM API equivalentlist_threads
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
sort_orderNostringPossible values: asc - oldest threads first and desc - newest threads first (default).
limitNonumberDefault: 3, maximum: 100
page_idNostring
min_events_countNonumberRange: 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.

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/get_chat
RTM API equivalentget_chat
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
thread_idNostringDefault: the latest thread (if exists)
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/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.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/start_chat
RTM API equivalentstart_chat
Webhookincoming_chat
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobjectInitial chat properties
chat.accessNoobjectChat access to set; default: all agents.
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial thread properties
continuousNoboolStarts chat as continuous (online group is not required); default: false.
Response
ParameterData typeNotes
chat_idstring
thread_idstring
event_ids[]stringReturned 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
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/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"
}

Activate Chat

Used to restart an archived chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/activate_chat
RTM API equivalentactivate_chat
Webhookincoming_chat
Request
Request objectRequiredTypeNotes
chatYesobject
chat.idYesstringID of the chat that will be activated.
chat.accessNoobjectChat access to set; default: all agents.
chat.propertiesNoobjectInitial chat properties
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial thread properties
continuousNoboolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Response
ParameterData typeNotes
thread_idstring
event_ids[]stringReturned only when the chat was activated with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/customer/action/activate_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 URLhttps://api.livechatinc.com/v3.2/customer/action/deactivate_chat
RTM API equivalentdeactivate_chat
Webhookincoming_event and chat_deactivated
Request
ParameterRequiredData type
chat_idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/deactivate_chat?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    "chat_id": "PWLW03ICW7"
    }'

Events

Send Event

Sends an Event object. Use this method to send a message by specifing the Message event type in the request.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/send_event
RTM API equivalentsend_event
Webhookincoming_event
Request
ParametersRequiredData typeNotes
chat_idYesstringId of the chat that you to send a message to.
eventYesobjectThe event object
attach_to_last_threadNoboolIf true, adds an event to last (inactive) thread. Otherwise, it doesn't creates a new one; default: false.
REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/send_event?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -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 URLhttps://api.livechatinc.com/v3.2/customer/action/upload_file
RTM API equivalent-
Webhookincoming_event *

*) incoming_event returns a URL that never expires.

Request
ParameterRequiredData typeNotes
fileYesbinaryMaximum size: 10MB
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/send_rich_message_postback
RTM API equivalentsend_rich_message_postback
Webhookincoming_rich_message_postback*

*) incoming_rich_message_postback will be sent only for active threads.

Request
ParameterRequiredData typeNotes
chat_idYesstring
event_idYesstring
postbackYesobject
postback.idYesstringPostback name of the button
postback.toggledYesboolPostback toggled; true or false
thread_idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/send_sneak_peek
RTM API equivalentsend_sneak_peek
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat to send a sneak peek to.
sneak_peek_textYesstringSneak peek text
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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"
    }'

Properties

Update Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/update_chat_properties
RTM API equivalentupdate_chat_properties
Webhookchat_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you to set a property for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/update_chat_properties?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    "chat_id": "Q1GZ3FNAT9",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "Chat property value updated by Customer"
        }
      }
    }'

Delete Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/delete_chat_properties
RTM API equivalentdelete_chat_properties
Webhookchat_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
propertiesYesobjectChat properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/delete_chat_properties?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    "chat_id": "Q1GZ3FNAT9",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": [
        "string_property"
        ]
      }
    }'

Update Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/update_thread_properties
RTM API equivalentupdate_thread_properties
Webhookthread_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
propertiesYesobjectChat properties to set.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/delete_thread_properties
RTM API equivalentdelete_thread_properties
Webhookthread_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
propertiesYesobjectThread properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/update_event_properties
RTM API equivalentupdate_event_properties
Webhookevent_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
event_idYesstringId of the event you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/delete_event_properties
RTM API equivalentdelete_event_properties
Webhookevent_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
event_idYesstringId of the event you want to delete the properties of.
propertiesYesobjectEvent properties to delete. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 MethodGET
Method URLhttps://api.livechatinc.com/v3.2/customer/action/list_license_properties
RTM API equivalent-
Webhook-
Request
Query string parameterRequiredData typeNotes
license_idYesnumberId of the license you want to return the properties of.
namespaceNostringProperty namespace to retrieve
nameNostringProperty name
REQUEST
Copied!
curl -X GET \
  'https://api.livechatinc.com/v3.2/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 MethodGET
Method URLhttps://api.livechatinc.com/v3.2/customer/action/list_group_properties
RTM API equivalent-
Webhook-
Request
Query string parameterRequiredData typeNotes
license_idYesnumberId of the license you want to return the properties of.
group_idYesnumberId of the group you want to return the properties of.
namespaceNostringProperty namespace to retrieve
nameNostringProperty name
REQUEST
Copied!
curl -X GET \
  'https://api.livechatinc.com/v3.2/customer/action/list_group_properties?license_id=11069052&group_id=1&namespace=0805e283233042b37f460ed8fbf22160&name=string_property' \
  -H 'Content-Type: application/json'
Response
Copied!
{
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "string value"
  }
}

Customers

Update Customer

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/update_customer
RTM API equivalentupdate_customer
Webhook-
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringThe URL of the Customer's avatar
session_fieldsNo[]objectAn 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).

REQUEST
Copied!
curl -X POST \
'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/set_customer_session_fields
RTM API equivalentset_customer_session_fields
Webhookcustomer_updated
Request
ParameterRequiredData typeNotes
session_fieldsYes[]objectAn 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).

REQUEST
Copied!
curl -X POST \
'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/get_customer
RTM API equivalentget_customer
Webhook-
Response
nameCustomer's name. Returned only if set.
emailCustomer's email. Returned only if set.
avatarCustomer's avatar. Returned only if set.
session_fieldsAn array of custom object-enclosed key:value pairs. Returned only if set. Available for the session duration.
REQUEST
Copied!
curl -X POST \
'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/list_group_statuses
RTM API equivalentlist_group_statuses
Webhook-
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, you will get statuses of all the groups.
group_idsNoarrayA 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 FoundIf you send group_id of a group that doesn't exists, the id won't be included in the resposne.
REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/check_goals
RTM API equivalent-
Webhook-
Request
ParameterRequiredData typeNotes
session_fieldsYes[]objectAn array of custom object-enclosed key:value pairs
group_idYesnumber
page_urlYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/get_form
RTM API equivalentget_form
Webhook-
Request
ParameterRequiredData typeNotes
group_idYesnumberId of the group from which you want the form.
typeYesstringForm type; possible values: prechat or postchat
Response
ParameterNotes
enabledIf enabled: false, the form object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI.
formThe form object
REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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": {
    "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"
          }
        ]
      }
    ]
  },
  "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 URLhttps://api.livechatinc.com/v3.2/customer/action/get_predicted_agent
RTM API equivalentget_predicted_agent
Webhook-
REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/get_predicted_agent?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{}'
Response
Copied!
{
  "id": "b5657aff34dd32e198160d54666df9d8",
  "name": "Agent Smith",
  "avatar": "https://example.avatar/example.com",
  "is_bot": false,
  "job_title": "support hero",
  "type": "agent"
}

Get URL Info

It returns the info on a given URL.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/customer/action/get_url_info
RTM API equivalentget_url_info
Webhook-
Request
ParameterRequiredData typeNotes
urlYesstringValid website URL
Response
ParameterData typeNotes
image_urlstringURL of the minified image hosted on the LiveChat's CDN
image_original_urlstringURL of the original image
REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/mark_events_as_seen
RTM API equivalentmark_events_as_seen
Webhookevents_marked_as_seen
Request
ParameterRequiredData typeNotes
chat_idYesstring
seen_up_toYesstringRFC 3339 date-time format
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/accept_greeting
RTM API equivalentaccept_greeting
Webhook-
Request
ParameterRequiredData typeNotes
greeting_idYesnumberID of the greeting configured within the license to accept.
unique_idYesstringID of the greeting to accept. You can get it from the incoming_greeting push.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/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 URLhttps://api.livechatinc.com/v3.2/customer/action/cancel_greeting
RTM API equivalentcancel_greeting
Webhook-
Request
ParameterRequiredData typeNotes
unique_idYesstringID of the greeting to cancel. You can get it from the incoming_greeting push.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  'https://api.livechatinc.com/v3.2/customer/action/cancel_greeting?license_id=<license_id>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <customer_access_token>' \
  -d '{
    "unique_id": "Q10X0W041P"
    }'

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.

You can create and manage webhooks via the Configuration API. Refer to this document to see the list of available webhooks, as well as sample payloads.

Errors

General error format
Copied!
{
  "error": {
  "type": "misdirected_request",
  "message": "Wrong region",
  "data": {
    // optional
    "region": "dal"
  }
  }
}

Possible errors

Error typeDefault messageDescription
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorUser is not allowed to perform the action.
customer_bannedCustomer is bannedThe customer had been banned.
entity_too_largeUpload limit exceeded (10MB).Client's request is too large.
greeting_not_foundGreeting not found
group_not_foundGroup not found
group_offlineGroup is offlineThrown in response to Get Predicted Agent.
group_unavailableNo agent available for groupThrown in response to Get Predicted Agent. The group is online, but there are no available Agents.
groups_offlineGroups offline
internalInternal server error
license_expiredLicense expiredThe end of license trial or subcription.
license_not_foundLicense not foundLicense with the specified ID doesn't exist.
misdirected_requestWrong regionClient'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_timeoutRequest timed outTimeout threshold is 15 seconds.
unsupported_versionUnsupported versionUnsupported protocol version.
validationWrong format of request
wrong_product_versionWrong product versionLicense 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@livechatinc.com. We'll be happy to hear from you!