Chats

List chats

Returns summaries of the chats an agent has access to. Specifics


Action	`list_chats`
Required scopes	or
Push message	—

Request

Parameter	Required	Type	Notes
`filters`	No	`object`	When paginating, filters from the first request are reused automatically. Providing a new `filters` object results in a `validation` error.
`filters.include_active`	No	`bool`	If set to `true`: includes active chats. Default: `true`.
`filters.include_chats_without_threads`	No	`bool`	If set to `true`: includes chats without any threads. Default: `true`.
`filters.group_ids`	No	`array`	An array of group IDs. Maximum 200.
`filters.properties.<namespace>.<name>.<filter_type>`¹	No	`any`	See ¹ below.
`sort_order`	No	`string`	`asc`: oldest chats first. `desc`: newest chats first. Default: `desc`.
`limit`	No	`number`	The maximum number of records per page. Default: `10`, maximum: `100`.
`page_id`	No	`string`	Cannot be combined with `filters`, `limit`, or `sort_order`.

<filter_type> values

Value	Type	Notes
`exists`	`bool`
`values`	`type[]`	An array with a specific type for the property: `string`, `int`, or `bool`.
`exclude_values`	`type[]`	An array with a specific type for the property: `string`, `int`, or `bool`.

There’s only one value allowed for a single property.

Response

Field	Type	Notes
`chats_summary`	`array`	An array of chat summary objects.
`next_page_id`	`string`	Present when there is a next page.
`previous_page_id`	`string`	Present when there is a previous page.
`found_chats`	`number`	An estimated count of found chats.

Request

{
  "action": "list_chats",
  "payload": {}
}

Response

{
  "request_id": "<request_id>",
  "action": "list_chats",
  "type": "response",
  "success": true,
  "payload": {
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "chats_summary": [
      {
        "id": "PJ0MRSHTDG",
        "last_event_per_type": {
          "message": {
            "thread_id": "K600PKZON8",
            "thread_created_at": "2020-05-07T07:11:28.288340Z",
            "event": {
              "id": "Q298LUVPRH_1",
              "created_at": "2019-12-09T12:01:18.909000Z",
              "visibility": "all",
              "type": "message",
              "text": "hello world",
              "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
            }
          },
          "system_message": {
            "thread_id": "K600PKZON8",
            "thread_created_at": "2020-05-07T07:11:28.288340Z",
            "event": {}
          }
        },
        "users": [],
        "last_thread_summary": {
          "id": "K600PKZON8",
          "created_at": "2020-05-07T07:11:28.288340Z",
          "user_ids": [
            "b7eff798-f8df-4364-8059-649c35c9ed0c",
            "smith@example.com"
          ],
          "properties": {},
          "active": true,
          "access": {
            "group_ids": [0]
          }
        },
        "properties": {},
        "access": {
          "group_ids": [0]
        },
        "is_followed": true
      }
    ],
    "found_chats": 4
  }
}

List threads

Returns threads the current agent has access to in a given chat. Specifics


Action	`list_threads`
Required scopes	or
Push message	—

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`sort_order`	No	`string`	`asc`: oldest threads first. `desc`: newest threads first. Default: `desc`.
`limit`	No	`number`	The maximum number of records per page. Default: `3`, maximum: `100`. Cannot be combined with `min_events_count`.
`page_id`	No	`string`
`min_events_count`	No	`number`	The minimum number of events to return in total across threads. Minimum: `1`, maximum: `100`. Cannot be combined with `limit` or `filters`.
`filters`	No	`object`	Cannot be combined with `min_events_count`.
`filters.from`	No	`string`	Date & time in RFC 3339 format with microsecond precision: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.to`	No	`string`	Date & time in RFC 3339 format with microsecond precision: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.

Response

Field	Type	Notes
`threads`	`array`	An array of thread objects.
`found_threads`	`number`
`next_page_id`	`string`	Present when there is a next page.
`previous_page_id`	`string`	Present when there is a previous page.

Request

{
  "action": "list_threads",
  "payload": {
    "chat_id": "PWJ8Y4THAV"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "list_threads",
  "type": "response",
  "success": true,
  "payload": {
    "threads": [
      {
        "id": "K600PKZON8",
        "created_at": "2019-12-17T07:57:41.512000Z",
        "active": true,
        "user_ids": [
          "b7eff798-f8df-4364-8059-649c35c9ed0c",
          "smith@example.com"
        ],
        "events": [
          {
            "id": "Q20N9CKRX2_1",
            "created_at": "2019-12-17T07:57:41.512000Z",
            "visibility": "all",
            "type": "message",
            "text": "Hello",
            "author_id": "smith@example.com"
          }
        ],
        "properties": {},
        "access": {
          "group_ids": [0]
        },
        "previous_thread_id": "K600PKZOM8",
        "next_thread_id": "K600PKZOO8"
      }
    ],
    "found_threads": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "previous_page_id": "MTUxNzM5ODEzMTQ5Nw=="
  }
}

Get chat

Returns a thread the current agent has access to in a given chat. Specifics


Action	`get_chat`
Required scopes	or
Push message	—

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`thread_id`	No	`string`	Default: the latest thread.

Response

Field	Type	Notes
`id`	`string`	The chat ID.
`thread`	`object`	A thread object.
`users`	`array`	An array of user objects.
`properties`	`object`
`access`	`object`
`is_followed`	`bool`

Request

{
  "action": "get_chat",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "get_chat",
  "type": "response",
  "success": true,
  "payload": {
    "id": "PJ0MRSHTDG",
    "thread": {
      "id": "K600PKZON8",
      "created_at": "2020-05-07T07:11:28.288340Z",
      "active": true,
      "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c", "smith@example.com"],
      "events": [
        {
          "id": "Q20N9CKRX2_1",
          "created_at": "2019-12-17T07:57:41.512000Z",
          "visibility": "all",
          "type": "message",
          "text": "Hello",
          "author_id": "smith@example.com"
        }
      ],
      "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,
        "created_at": "2019-12-17T08:53:20.693553+01:00",
        "statistics": {
          "chats_count": 1
        },
        "agent_last_event_created_at": "2019-12-17T09:04:05.239000+01:00"
      },
      {
        "id": "smith@example.com",
        "name": "Agent Smith",
        "email": "smith@example.com",
        "type": "agent",
        "present": true,
        "avatar": "https://example.com/avatar.jpg",
        "visibility": "all"
      }
    ],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string_value"
      }
    },
    "access": {
      "group_ids": [0]
    },
    "is_followed": true
  }
}

List archives

Returns a list of the chats an agent has access to. Together with a chat, the events of one thread from this chat are returned. The list classification is based on threads — one chat per thread. The same chat may appear on the list several times, each time with a different thread. The returned chat is a complete object, not only a chat summary. Specifics


Action	`list_archives`
Required scopes	or
Push message	—

Request

Parameter	Required	Type	Notes
`filters`	No	`object`
`filters.query`	No	`string`
`filters.from`	No	`string`	Date & time in RFC 3339 format with microsecond precision.
`filters.to`	No	`string`	Date & time in RFC 3339 format with microsecond precision.
`filters.group_ids`	No	`array`	An array of group IDs. Maximum 200.
`filters.properties.<namespace>.<name>.<properties_filter_type>`¹	No	`any`	See ¹ below.
`filters.agents.<filter_type>`²	No	`any`	See ² below. If `exists` is `false`: returns unassigned chats. If `true`: returns assigned chats.
`filters.tags.<filter_type>`²	No	`any`	See ² below.
`filters.sales.<filter_type>`²	No	`any`	See ² below.
`filters.goals.<filter_type>`²	No	`any`	See ² below.
`filters.forms.<form>`³	No	`array`	See ³ below.
`filters.event_types.<event_type_filter_type>`⁴	No	`any`	See ⁴ below.
`filters.greetings.<greetings_filter_type>`⁵	No	`any`	See ⁵ below.
`filters.agent_response.<agent_response_filter_type>`⁶	No	`any`	See ⁶ below.
`filters.customer_countries.<filter_type>`²	No	`any`	See ² below. Supports country codes in ISO 3166-1 Alpha-2 format.
`page_id`	No	`string`
`sort_order`	No	`string`	`asc`: oldest chats first. `desc`: newest chats first. Default: `desc`.
`limit`	No	`number`	The maximum number of records per page. Default: `10`, minimum: `1`, maximum: `100`.
`highlights`	No	`object`	Highlights the match of `filters.query`. Pass an empty object to enable with default settings.
`highlights.pre_tag`	No	`string`	An HTML tag used to open the highlighted match. Default: `<em>`.
`highlights.post_tag`	No	`string`	An HTML tag used to close the highlighted match. Default: `</em>`.

<properties_filter_type> values

Value	Type	Notes
`exists`	`bool`
`values`	`type[]`	An array with a specific type: `string`, `int`, or `bool`.
`exclude_values`	`type[]`	An array with a specific type: `string`, `int`, or `bool`.

There’s only one value allowed for a single property.

<filter_type> values

| Value | Type | Notes | | --- | --- | --- | | exists | bool | | | values | type[] | | | exclude_values | type[] | | | require_every_value | bool | If true, returns only chats that have all elements passed in values or exclude_values. |

<form> fields

| Field | Type | Notes | | --- | --- | --- | | type | string | pre_chat or post_chat. | | answer_id | string | |

<event_type_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | values | string[] | An array of Event types. | | exclude_values | string[] | An array of Event types. | | require_every_value | bool | |

<greetings_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | from | string | Date & time in RFC 3339 format with microsecond precision. | | to | string | Date & time in RFC 3339 format with microsecond precision. | | exists | bool | | | values | int[] | An array of greeting IDs. | | exclude_values | int[] | An array of greeting IDs. | | groups.values | int[] | An array of group IDs. | | groups.exclude_values | int[] | An array of group IDs. |

<agent_response_filter_type> values

| Value | Type | Notes | | --- | --- | --- | | exists | bool | | | first | bool | Modifier that makes other agent_response filters apply only to agents’ first response. | | agents.values | string[] | An array of agent IDs. | | agents.exclude_values | string[] | An array of agent IDs. | | groups.values | int[] | An array of group IDs. | | groups.exclude_values | int[] | An array of group IDs. |

Response

Field	Type	Notes
`chats`	`array`	An array of complete chat objects (not summaries).
`found_chats`	`number`
`next_page_id`	`string`	Present when there is a next page.
`previous_page_id`	`string`	Present when there is a previous page.

Request

{
  "action": "list_archives",
  "payload": {
    "filters": {
      "event_types": {
        "values": ["message", "filled_form"]
      }
    }
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "list_archives",
  "type": "response",
  "success": true,
  "payload": {
    "chats": [
      {
        "id": "PJ0MRSHTDG",
        "users": [
          {
            "id": "smith@example.com",
            "name": "Agent Smith",
            "email": "smith@example.com",
            "type": "agent",
            "present": true,
            "avatar": "https://cdn.livechat-files.com/api/file/avatar.png",
            "visibility": "all"
          }
        ],
        "thread": {
          "id": "K600PKZON8",
          "active": false,
          "user_ids": ["smith@example.com"],
          "events": [
            {
              "id": "QBT14H0Y3Y_1",
              "created_at": "2020-05-28T11:45:32.269000Z",
              "visibility": "all",
              "type": "message",
              "properties": {
                "0805e283233042b37f460ed8fbf22160": {
                  "event_property": "property_value"
                }
              },
              "text": "Hello, how can I help you?",
              "author_id": "smith@example.com"
            }
          ],
          "properties": {
            "0805e283233042b37f460ed8fbf22160": {
              "thread_property": "property_value"
            }
          },
          "access": {
            "group_ids": [0]
          },
          "created_at": "2020-05-28T11:44:58.829000Z",
          "previous_thread_id": "K600PKZOM8",
          "next_thread_id": "K600PKZOO8",
          "previous_accessible_thread_id": "K600PKZOM8",
          "next_accessible_thread_id": "K600PKZOO8"
        },
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "chat_property": "property_value"
          }
        },
        "access": {
          "group_ids": [0]
        },
        "is_followed": false
      }
    ],
    "found_chats": 42,
    "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
    "previous_page_id": "MTUxNzM5ODEzMTQ5Ng=="
  }
}

Start chat

Starts a chat. Authors (except the requester) of all initial events must be listed in the users field. The default visibility of both events and users is all and cannot be changed. The method updates the requester’s events_seen_up_to as if they’ve seen all chat events. Specifics


Action	`start_chat`
Required scopes	or
Push message	`incoming_chat`

Request

Parameter	Required	Type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`
`chat.access`	No	`object`
`chat.users`	No	`[]object`	A list of existing users. Up to 4 additional agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	The user ID. Required when `chat.users` is provided.
`chat.users.type`	Yes	`string`	Possible values: `agent`, `customer`. Required when `chat.users` is provided.
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	The list of initial chat events. Does not support the `form` type event in Text.
`chat.thread.properties`	No	`object`
`active`	No	`bool`	If set to `true`: creates an active thread. Default: `true`.
`continuous`	No	`bool`	If set to `true`: starts the chat as continuous (online group not required). Default: `false`.

Response

Field	Type	Notes
`chat_id`	`string`
`thread_id`	`string`
`event_ids`	`[]string`	Returned only when the chat was started with initial events. Includes only user-generated event IDs.

Request

{
  "action": "start_chat",
  "payload": {}
}

Response

{
  "request_id": "<request_id>",
  "action": "start_chat",
  "type": "response",
  "success": true,
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "PGDGHT5G"
  }
}

Resume chat

Restarts an archived chat. Authors (except the requester) of all initial events must be listed in the users field. The default visibility of both events and users is all and cannot be changed. The method updates the requester’s events_seen_up_to as if they’ve seen all chat events. Specifics


Action	`resume_chat`
Required scopes	or
Push message	`incoming_chat`

Request

Parameter	Required	Type	Notes
`chat`	Yes	`object`
`chat.id`	Yes	`string`	The ID of the chat to resume.
`chat.access`	No	`object`	The chat access to set. Default: all agents.
`chat.properties`	No	`object`	The initial chat properties.
`chat.users`	No	`[]object`	A list of existing users. Up to 4 additional agents and 1 customer allowed.
`chat.users.id`	Yes	`string`	The user ID. Required when `chat.users` is provided.
`chat.users.type`	Yes	`string`	Possible values: `agent`, `customer`. Required when `chat.users` is provided.
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	The initial chat events array.
`chat.thread.properties`	No	`object`	The initial thread properties.
`active`	No	`bool`	If set to `false`: creates an inactive thread. Default: `true`.
`continuous`	No	`bool`	If set to `true`: sets the chat to continuous mode. When unset, leaves the mode unchanged.

Response

Field	Type	Notes
`thread_id`	`string`
`event_ids`	`[]string`	Returned only when the chat was resumed with initial events. Includes only user-generated event IDs.

Request

{
  "action": "resume_chat",
  "payload": {
    "chat": {
      "id": "PWJ8Y4THAV"
    }
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "resume_chat",
  "type": "response",
  "success": true,
  "payload": {
    "thread_id": "Z8AGR5OUW"
  }
}

Deactivate chat

Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible. The requester must be present on the list of chat users. Override this by setting ignore_requester_presence. Specifics


Action	`deactivate_chat`
Required scopes	or
Push message	`chat_deactivated`

Request

Parameter	Required	Type	Notes
`id`	Yes	`string`	The chat ID.
`ignore_requester_presence`	No	`bool`	If set to `true`: the requester doesn’t need to be on the list of chat users. Default: `false`.

No response payload.

Request

{
  "action": "deactivate_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "deactivate_chat",
  "type": "response",
  "success": true,
  "payload": {}
}

Follow chat

Marks a chat as followed. All changes to the chat will be sent to the requester until the chat is reactivated or unfollowed. Chat members don’t need to follow their chats — they receive all chat pushes regardless of their follower status. Specifics


Action	`follow_chat`
Required scopes	or
Push message	`incoming_chat`*

* Not sent when the requester already follows the chat or is a chat member. Request

Parameter	Required	Type	Notes
`id`	Yes	`string`	The chat ID.

No response payload.

Request

{
  "action": "follow_chat",
  "payload": {
    "id": "PW94SJTGW6"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "follow_chat",
  "type": "response",
  "success": true,
  "payload": {}
}

Unfollow chat

Removes the requester from the chat followers. After that, only key changes to the chat (like transfer_chat or close_active_thread) will be sent to the requester. Chat members cannot unfollow the chat. Specifics


Action	`unfollow_chat`
Required scopes	—
Push message	`chat_unfollowed`

Request

Parameter	Required	Type	Notes
`id`	Yes	`string`	The chat ID.

Response

Field	Type	Notes
`chat_id`	`string`

Request

{
  "action": "unfollow_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}

Response

{
  "request_id": "<request_id>",
  "action": "unfollow_chat",
  "type": "response",
  "success": true,
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}

Overview

Methods

List chats

List threads

Get chat

List archives

Start chat

Resume chat

Deactivate chat

Follow chat

Unfollow chat

​List chats

​List threads

​Get chat

​List archives

​Start chat

​Resume chat

​Deactivate chat

​Follow chat

​Unfollow chat

List chats

List threads

Get chat

List archives

Start chat

Resume chat

Deactivate chat

Follow chat

Unfollow chat