> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chats

> Reference of Chats methods for the Agent Chat RTM API v3.6.

## List chats

Returns summaries of the chats an agent has access to.

**Specifics**

|                     |                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**          | `list_chats`                                                                                                                                                                   |
| **Required scopes** | <Tooltip tip="To find chats from all groups.">`chats--all:ro`</Tooltip> or <Tooltip tip="To find chats from groups the requester is a member of.">`chats--access:ro`</Tooltip> |
| **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.active`                                                  | No       | `bool`   | If set to `true`: returns active chats only. If set to `false`: returns inactive chats only. If not provided: returns both active and inactive chats. |
| `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>`<sup>1</sup> | No       | `any`    | See <sup>1</sup> 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`.                                                                                          |

<Accordion title="<filter_type> values" icon="1">
  | 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.
</Accordion>

**Response**

| Field              | Type     | Notes                                                                                        |
| ------------------ | -------- | -------------------------------------------------------------------------------------------- |
| `chats_summary`    | `array`  | An array of [chat summary objects](/api/agent-chat/v3.6/rtm/data-structures#chat-summaries). |
| `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.                                                           |

```json title="Request" theme={null}
{
  "action": "list_chats",
  "payload": {}
}
```

```json title="Response" theme={null}
{
  "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** | <Tooltip tip="To find threads from all groups.">`chats--all:ro`</Tooltip> or <Tooltip tip="To find threads from groups the requester is a member of.">`chats--access:ro`</Tooltip> |
| **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](/api/agent-chat/v3.6/rtm/data-structures#threads). |
| `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.                                          |

```json title="Request" theme={null}
{
  "action": "list_threads",
  "payload": {
    "chat_id": "PWJ8Y4THAV"
  }
}
```

```json title="Response" theme={null}
{
  "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"
          }
        ],
        "summary": {
          "status": "ok",
          "text": "• Agent greets with a short message.",
          "updated_at": "2025-10-21T07:08:16.125000Z"
        },
        "properties": {},
        "access": {
          "group_ids": [0]
        },
        "previous_thread_id": "K600PKZOM8",
        "next_thread_id": "K600PKZOO8",
        "customer_visit": {
          "ip": "<customer_ip>",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
          "geolocation": {
            "latitude": "-14.6973803",
            "longitude": "-75.1266898",
            "country": "Poland",
            "country_code": "PL",
            "region": "Dolnoslaskie",
            "city": "Wroclaw",
            "timezone": "Europe/Warsaw"
          }
        }
      }
    ],
    "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** | <Tooltip tip="To get a chat from any group.">`chats--all:ro`</Tooltip> or <Tooltip tip="To get a chat from a group the requester is a member of.">`chats--access:ro`</Tooltip> |
| **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](/api/agent-chat/v3.6/rtm/data-structures#threads).        |
| `users`       | `array`  | An array of [user objects](/api/agent-chat/v3.6/rtm/data-structures#users). |
| `properties`  | `object` |                                                                             |
| `access`      | `object` |                                                                             |
| `is_followed` | `bool`   |                                                                             |

```json title="Request" theme={null}
{
  "action": "get_chat",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8"
  }
}
```

```json title="Response" theme={null}
{
  "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"
        }
      ],
      "summary": {
        "status": "ok",
        "text": "• Agent greets with a short message.",
        "updated_at": "2025-10-21T07:08:16.125000Z"
      },
      "properties": {
        "0805e283233042b37f460ed8fbf22160": {
          "string_property": "string_value"
        }
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8",
      "next_thread_id": "K600PKZOO8",
      "customer_visit": {
        "ip": "<customer_ip>",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
        "geolocation": {
          "latitude": "-14.6973803",
          "longitude": "-75.1266898",
          "country": "Poland",
          "country_code": "PL",
          "region": "Dolnoslaskie",
          "city": "Wroclaw",
          "timezone": "Europe/Warsaw"
        }
      }
    },
    "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** | <Tooltip tip="To find threads from all groups.">`chats--all:ro`</Tooltip> or <Tooltip tip="To find threads from groups the requester is a member of.">`chats--access:ro`</Tooltip> |
| **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.chat_ids`                                                           | No       | `array`  | An array of chat IDs. Maximum 1000.                                                                          |
| `filters.thread_ids`                                                         | No       | `array`  | An array of thread IDs. Cannot be combined with other filters or pagination. Maximum 20.                     |
| `filters.group_ids`                                                          | No       | `array`  | An array of group IDs. Maximum 200.                                                                          |
| `filters.properties.<namespace>.<name>.<properties_filter_type>`<sup>1</sup> | No       | `any`    | See <sup>1</sup> below.                                                                                      |
| `filters.agents.<filter_type>`<sup>2</sup>                                   | No       | `any`    | See <sup>2</sup> below. If `exists` is `false`: returns unassigned chats. If `true`: returns assigned chats. |
| `filters.tags.<filter_type>`<sup>2</sup>                                     | No       | `any`    | See <sup>2</sup> below.                                                                                      |
| `filters.sales.<filter_type>`<sup>2</sup>                                    | No       | `any`    | See <sup>2</sup> below.                                                                                      |
| `filters.goals.<filter_type>`<sup>2</sup>                                    | No       | `any`    | See <sup>2</sup> below.                                                                                      |
| `filters.forms.<form>`<sup>3</sup>                                           | No       | `array`  | See <sup>3</sup> below.                                                                                      |
| `filters.event_types.<event_type_filter_type>`<sup>4</sup>                   | No       | `any`    | See <sup>4</sup> below.                                                                                      |
| `filters.greetings.<greetings_filter_type>`<sup>5</sup>                      | No       | `any`    | See <sup>5</sup> below.                                                                                      |
| `filters.agent_response.<agent_response_filter_type>`<sup>6</sup>            | No       | `any`    | See <sup>6</sup> below.                                                                                      |
| `filters.agent_types.<agent_type_filter_type>`<sup>7</sup>                   | No       | `any`    | See <sup>7</sup> below.                                                                                      |
| `filters.ecommerce_sales.<ecommerce_sales_filter_type>`<sup>8</sup>          | No       | `any`    | See <sup>8</sup> below.                                                                                      |
| `filters.customer_countries.<filter_type>`<sup>2</sup>                       | No       | `any`    | See <sup>2</sup> below. Supports country codes in ISO 3166-1 Alpha-2 format.                                 |
| `filters.customer_id`                                                        | No       | `string` |                                                                                                              |
| `filters.customer_email`                                                     | No       | `string` |                                                                                                              |
| `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>`.                                           |

<Accordion title="<properties_filter_type> values" icon="1">
  | 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.
</Accordion>

<Accordion title="<filter_type> values" icon="2">
  \| 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`. |
</Accordion>

<Accordion title="<form> fields" icon="3">
  \| Field | Type | Notes | | --- | --- | --- | | `type` | `string` | `pre_chat`
  or `post_chat`. | | `answer_id` | `string` | |
</Accordion>

<Accordion title="<event_type_filter_type> values" icon="4">
  \| Value | Type | Notes | | --- | --- | --- | | `values` | `string[]` | An
  array of Event types. | | `exclude_values` | `string[]` | An array of Event
  types. | | `require_every_value` | `bool` | |
</Accordion>

<Accordion title="<greetings_filter_type> values" icon="5">
  \| 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. |
</Accordion>

<Accordion title="<agent_response_filter_type> values" icon="6">
  \| 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. |
</Accordion>

<Accordion title="<agent_type_filter_type> values" icon="7">
  | Value            | Type       | Notes                          |
  | ---------------- | ---------- | ------------------------------ |
  | `all_values`     | `string[]` | An array of agent type values. |
  | `any_values`     | `string[]` | An array of agent type values. |
  | `exclude_values` | `string[]` | An array of agent type values. |

  Allowed agent type values: `human`, `chatbot`, `ai_agent`. Each value can be used only once across all arrays. You can provide more than one filter type at a time.
</Accordion>

<Accordion title="<ecommerce_sales_filter_type> values" icon="8">
  | Value            | Type       | Notes                                    |
  | ---------------- | ---------- | ---------------------------------------- |
  | `all_values`     | `string[]` | An array of ecommerce sales type values. |
  | `any_values`     | `string[]` | An array of ecommerce sales type values. |
  | `exclude_values` | `string[]` | An array of ecommerce sales type values. |

  Allowed ecommerce sales type values: `direct`, `indirect`. Each value can be used only once across all arrays. You can provide more than one filter type at a time.
</Accordion>

**Response**

| Field              | Type     | Notes                                                                                                |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `chats`            | `array`  | An array of complete [chat objects](/api/agent-chat/v3.6/rtm/data-structures#chats) (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.                                                               |

```json title="Request" theme={null}
{
  "action": "list_archives",
  "payload": {
    "filters": {
      "event_types": {
        "values": ["message", "filled_form"]
      }
    }
  }
}
```

```json title="Response" theme={null}
{
  "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"
            }
          ],
          "summary": {
            "status": "ok",
            "text": "• Agent greets with a short message.",
            "updated_at": "2025-10-21T07:08:16.125000Z"
          },
          "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",
          "customer_visit": {
            "ip": "<customer_ip>",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
            "geolocation": {
              "latitude": "-14.6973803",
              "longitude": "-75.1266898",
              "country": "Poland",
              "country_code": "PL",
              "region": "Dolnoslaskie",
              "city": "Wroclaw",
              "timezone": "Europe/Warsaw"
            }
          }
        },
        "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** | <Tooltip tip="To start a chat in any group.">`chats--all:rw`</Tooltip> or <Tooltip tip="To start a chat in groups the requester is a member of.">`chats--access:rw`</Tooltip> |
| **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. |

```json title="Request" theme={null}
{
  "action": "start_chat",
  "payload": {}
}
```

```json title="Response" theme={null}
{
  "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** | <Tooltip tip="To resume a chat in any group.">`chats--all:rw`</Tooltip> or <Tooltip tip="To resume a chat in groups the requester is a member of.">`chats--access:rw`</Tooltip> |
| **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. |

```json title="Request" theme={null}
{
  "action": "resume_chat",
  "payload": {
    "chat": {
      "id": "PWJ8Y4THAV"
    }
  }
}
```

```json title="Response" theme={null}
{
  "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** | <Tooltip tip="To deactivate a chat in any group.">`chats--all:rw`</Tooltip> or <Tooltip tip="To deactivate a chat in groups the agent is a member of.">`chats--access:rw`</Tooltip> |
| **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.

```json title="Request" theme={null}
{
  "action": "deactivate_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}
```

```json title="Response" theme={null}
{
  "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** | <Tooltip tip="To follow chats from all groups.">`chats--all:ro`</Tooltip> or <Tooltip tip="To follow chats from groups the requester is a member of.">`chats--access:ro`</Tooltip> |
| **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.

```json title="Request" theme={null}
{
  "action": "follow_chat",
  "payload": {
    "id": "PW94SJTGW6"
  }
}
```

```json title="Response" theme={null}
{
  "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` |       |

```json title="Request" theme={null}
{
  "action": "unfollow_chat",
  "payload": {
    "id": "PJ0MRSHTDG"
  }
}
```

```json title="Response" theme={null}
{
  "request_id": "<request_id>",
  "action": "unfollow_chat",
  "type": "response",
  "success": true,
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}
```
