Web API Reference

Introduction

Versioning

This document describes the Customer Chat Web API v3.2. This is the deprecated version. We encourage you to migrate to the latest stable version. Read more about versioning...

Lifecycle headers

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

What is Web API

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

When to use Web API

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

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

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

Access

Customer authentication is handled with access tokens. Find out how to get an access token from Customer authorization flow. Take note that it's not the same token you would use for the Agent Chat or Configuration API.

Data centers

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

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

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

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

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.

Data structures

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

Methods

HTTP method	The API endpoint	Methods
POST	`https://api.livechatinc.com/v3.2/customer/action/<action>`	All except for Get License Properties and Get Group Properties
GET	`https://api.livechatinc.com/v3.2/customer/action/<action>`	Get License Properties and Get Group Properties

Header	Value	Notes
`X-API-Version`	`3.2`	Not needed if you specify the API version in the URL.
`Content-Type`	`multipart/form-data; boundary=<boundary>`	Valid for the Upload File method
`Content-Type`	`application/json`	Valid for every method except for Upload File
`Authorization`	`Bearer <token>`	Customer access token. It's not the same token you would use for the Agent Chat or Configuration API. Not needed for Get License Properties and Get Group Properties. Read more...

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

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

Query string parameter	Data type	Notes	Methods
`license_id`	`integer`	LiveChat account ID	All

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


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

Chats

List Chats

It returns summaries of the chats a Customer participated in.

Specifics


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

Request

Parameter	Required	Type	Notes
`limit`	No	`number`	Default: 10, maximum: 25
`sort_order`	No	`string`	Possible values: `asc`, `desc` (default). Chat summaries are sorted by the creation date of its last thread.
`page_id`	No	`string`

Response

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

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 URL	`https://api.livechatinc.com/v3.2/customer/action/list_threads`
RTM API equivalent	`list_threads`
Webhook	-

Request

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.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/get_chat`
RTM API equivalent	`get_chat`
Webhook	-

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`thread_id`	No	`string`	Default: 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 URL	`https://api.livechatinc.com/v3.2/customer/action/start_chat`
RTM API equivalent	`start_chat`
Webhook	`incoming_chat`

Request

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. Does not support the `form` type event in the LiveChat app.
`chat.thread.properties`	No	`object`	Initial thread properties
`continuous`	No	`bool`	Starts chat as continuous (online group is not required); default: `false`.

Response

Field	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

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 URL	`https://api.livechatinc.com/v3.2/customer/action/activate_chat`
RTM API equivalent	`activate_chat`
Webhook	`incoming_chat`

Request

Parameter	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 thread properties
`continuous`	No	`bool`	Sets a chat to the continuous mode. When unset, leaves the mode unchanged.

Response

Field	Data type	Notes
`thread_id`	`string`
`event_ids`	`[]string`	Returned 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 URL	`https://api.livechatinc.com/v3.2/customer/action/deactivate_chat`
RTM API equivalent	`deactivate_chat`
Webhook	`incoming_event` and `chat_deactivated`

Request

Parameter	Required	Data type
`chat_id`	Yes	`string`

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 specifying the Message event type in the request.

The method updates the requester's events_seen_up_to as if they've seen all chat events.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/customer/action/send_event`
RTM API equivalent	`send_event`
Webhook	`incoming_event`

Request

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

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 URL	`https://api.livechatinc.com/v3.2/customer/action/upload_file`
RTM API equivalent	-
Webhook	`incoming_event` *

*) incoming_event returns a URL that never expires.

Request

Parameter	Required	Data type	Notes
`file`	Yes	`binary`	Maximum 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 URL	`https://api.livechatinc.com/v3.2/customer/action/send_rich_message_postback`
RTM API equivalent	`send_rich_message_postback`
Webhook	`incoming_rich_message_postback`*

*) incoming_rich_message_postback will be sent only for active threads.

Request

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`

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 URL	`https://api.livechatinc.com/v3.2/customer/action/send_sneak_peek`
RTM API equivalent	`send_sneak_peek`
Webhook	-

Request

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

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 URL	`https://api.livechatinc.com/v3.2/customer/action/update_chat_properties`
RTM API equivalent	`update_chat_properties`
Webhook	`chat_properties_updated`

Request

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.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/delete_chat_properties`
RTM API equivalent	`delete_chat_properties`
Webhook	`chat_properties_deleted`

Request

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.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/update_thread_properties`
RTM API equivalent	`update_thread_properties`
Webhook	`thread_properties_updated`

Request

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.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/delete_thread_properties`
RTM API equivalent	`delete_thread_properties`
Webhook	`thread_properties_deleted`

Request

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

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 URL	`https://api.livechatinc.com/v3.2/customer/action/update_event_properties`
RTM API equivalent	`update_event_properties`
Webhook	`event_properties_updated`

Request

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.
`event_id`	Yes	`string`	Id of the event 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.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/delete_event_properties`
RTM API equivalent	`delete_event_properties`
Webhook	`event_properties_deleted`

Request

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. 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 Method	GET
Method URL	`https://api.livechatinc.com/v3.2/customer/action/list_license_properties`
RTM API equivalent	-
Webhook	-

Request

Query string parameter	Required	Data type	Notes
`license_id`	Yes	`number`	Id of the license you want to return the properties of.
`namespace`	No	`string`	Property namespace to retrieve
`name`	No	`string`	Property 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 Method	GET
Method URL	`https://api.livechatinc.com/v3.2/customer/action/list_group_properties`
RTM API equivalent	-
Webhook	-

Request

Query string parameter	Required	Data type	Notes
`license_id`	Yes	`number`	Id of the license you want to return the properties of.
`group_id`	Yes	`number`	Id of the group you want to return the properties of.
`namespace`	No	`string`	Property namespace to retrieve
`name`	No	`string`	Property name

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 URL	`https://api.livechatinc.com/v3.2/customer/action/update_customer`
RTM API equivalent	`update_customer`
Webhook	-

Request

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

At least one optional parameter needs to be included in the request.

When updating customer data while the customer has an active chat, the update will take effect after the chat has ended.

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": "https://example.com/avatars/1.png",
    "session_fields": [{
    "custom_key": "custom_value"
    }, {
    "another_custom_key": "another_custom_value"
    }]
  }'

Set Customer Session Fields

Specifics


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

Request

Parameter	Required	Data type	Notes
`session_fields`	Yes	`[]object`	An 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 URL	`https://api.livechatinc.com/v3.2/customer/action/get_customer`
RTM API equivalent	`get_customer`
Webhook	-

Response


`name`	Customer's name. Returned only if set.
`email`	Customer's email. Returned only if set.
`avatar`	Customer's avatar. Returned only if set.
`session_fields`	An array of custom object-enclosed `key:value` pairs. Returned only if set. Available for the session duration.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/list_group_statuses`
RTM API equivalent	`list_group_statuses`
Webhook	-

Request

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

One of the optional parameters needs to be included in the request.

Response

No response payload (200 OK).

Response


`Group Not Found`	If 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 URL	`https://api.livechatinc.com/v3.2/customer/action/check_goals`
RTM API equivalent	-
Webhook	-

Request

Parameter	Required	Data type	Notes
`session_fields`	Yes	`[]object`	An array of custom object-enclosed `key:value` pairs
`group_id`	Yes	`number`
`page_url`	Yes	`string`

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 URL	`https://api.livechatinc.com/v3.2/customer/action/get_form`
RTM API equivalent	`get_form`
Webhook	-

Request

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`

Response

Field	Notes
`enabled`	If `enabled: false`, the `form` object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI.
`form`	The `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 URL	`https://api.livechatinc.com/v3.2/customer/action/get_predicted_agent`
RTM API equivalent	`get_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 URL	`https://api.livechatinc.com/v3.2/customer/action/get_url_info`
RTM API equivalent	`get_url_info`
Webhook	-

Request

Parameter	Required	Data type	Notes
`url`	Yes	`string`	Valid website URL

Response

Field	Data type	Notes
`image_url`	`string`	URL of the minified image hosted on the LiveChat's CDN
`image_original_url`	`string`	URL of the original image

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 URL	`https://api.livechatinc.com/v3.2/customer/action/mark_events_as_seen`
RTM API equivalent	`mark_events_as_seen`
Webhook	`events_marked_as_seen`

Request

Parameter	Required	Data type	Notes
`chat_id`	Yes	`string`
`seen_up_to`	Yes	`string`	RFC 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 URL	`https://api.livechatinc.com/v3.2/customer/action/accept_greeting`
RTM API equivalent	`accept_greeting`
Webhook	-

Request

Parameter	Required	Data type	Notes
`greeting_id`	Yes	`number`	ID of the greeting configured within the license to accept.
`unique_id`	Yes	`string`	ID of the greeting to accept. You can get it from the `incoming_greeting` push.

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 URL	`https://api.livechatinc.com/v3.2/customer/action/cancel_greeting`
RTM API equivalent	`cancel_greeting`
Webhook	-

Request

Parameter	Required	Data type	Notes
`unique_id`	Yes	`string`	ID 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.

See webhook methods See webhook payloads

Errors

General error format

Copied!

{
  "error": {
    "type": "misdirected_request",
    "message": "Wrong region",
    "data": {
      // optional
      "region": "dal"
    }
  }
}

Possible errors

Error type	Default message	Description
`authentication`	Authentication error	An invalid or expired access token.
`authorization`	Authorization error	User is not allowed to perform the action.
`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. The correct region is returned in the optional data object – this is where the client should be connected.
`request_timeout`	Request timed out	Timeout threshold is 15 seconds.
`too_many_requests`	Too many requests	The request's rate limit was exceeded. It'll be unblocked automatically after some time.
`unsupported_version`	Unsupported version	Unsupported protocol version.
`validation`	Wrong format of request
`wrong_product_version`	Wrong product version	License is not LiveChat 3 (probably still LiveChat 2).

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@text.com. We'll be happy to hear from you!

Web API Reference.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

Versioning

Lifecycle headers

What is Web API

When to use Web API

Access

Data centers

Postman Collection

Data structures

Methods

Available methods

Chats

List Chats

Specifics

Request

Response

List Threads

Specifics

Request

Get Chat

Specifics

Request

Start Chat

Specifics

Request

Response

Activate Chat

Specifics

Request

Response

Deactivate Chat

Specifics

Request

Response

Events

Send Event

Specifics

Request

Upload File

Specifics

Request

Send Rich Message Postback

Specifics

Request

Response

Send Sneak Peek

Specifics

Request

Response

Properties

Update Chat Properties

Specifics

Request

Response

Delete Chat Properties

Specifics

Request

Response

Update Thread Properties

Specifics

Request

Response

Delete Thread Properties

Specifics

Request

Response

Update Event Properties

Specifics

Request

Response

Delete Event Properties

Specifics

Request

Response

List License Properties

Specifics

Request

List Group Properties

Specifics

Request

Web API Reference