Chats

List chats

Returns summaries of the chats a customer participated in. Specifics


Action	`list_chats`
Web API equivalent	`list_chats`
Push message	—

Request

Parameter	Required	Type	Notes
`limit`	No	`number`	The maximum number of records returned per page. Default: `10`, maximum: `25`. Chat summaries are sorted by the creation date of the last thread.
`sort_order`	No	`string`	Possible values: `asc`, `desc`. Default: `desc`.
`page_id`	No	`string`

Response

Field	Type	Notes
`total_chats`	`number`	An estimated number. The real number of found chats can slightly differ.
`next_page_id`	`string`	Present when there is a next page.
`previous_page_id`	`string`	Present when there is a previous page.
`chats_summary`	`array`	An array of chat summary data structures.

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_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": {},
        "active": true
      }
    ],
    "total_chats": 1
  }
}

List threads

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


Action	`list_threads`
Web API equivalent	`list_threads`
Push message	—

Request

Parameter	Required	Type	Notes
`chat_id`	Yes	`string`
`sort_order`	No	`string`	Possible values: `asc`, `desc`. Default: `desc`.
`limit`	No	`number`	The maximum number of records returned per page. Default: `3`, maximum: `100`.
`page_id`	No	`string`
`min_events_count`	No	`number`	The minimum number of events to be returned in the response. This is 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 condition. Minimum: `1`, maximum: `100`. Cannot be used together with `limit`.

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",
          "bbb67d600796e9f277e360e842418833"
        ],
        "events": [
          {
            "id": "Q20N9CKRX2_1",
            "created_at": "2019-12-17T07:57:41.512000Z",
            "recipients": "all",
            "type": "message",
            "text": "Hello",
            "author_id": "bbb67d600796e9f277e360e842418833"
          }
        ],
        "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

Specifics


Action	`get_chat`
Web API equivalent	`get_chat`
Push message	—

Request

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

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",
        "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. Updates the requester’s events_seen_up_to as if they’ve seen all chat events. Specifics


Action	`start_chat`
Web API equivalent	`start_chat`
Push message	`incoming_chat`

Request

Parameter	Required	Type	Notes
`chat`	No	`object`
`chat.properties`	No	`object`	The initial chat properties.
`chat.access`	No	`object`	The chat access to set. Default: all agents.
`chat.users`	No	`array`	A list of existing users. Only one user is allowed (type `customer`).
`chat.thread`	No	`object`
`chat.thread.events`	No	`array`	Initial chat events array. Does not support the `form` type event in Text.
`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`: starts the chat as continuous (online group is not required).

Response

Field	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.

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. Updates the requester’s events_seen_up_to as if they’ve seen all chat events. Specifics


Action	`resume_chat`
Web API equivalent	`resume_chat`
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.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. If set to `false`: sets the chat to non-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. Returns only the IDs of user-generated events; server-side generated events are not included.

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. Specifics


Action	`deactivate_chat`
Web API equivalent	`deactivate_chat`
Push message	`incoming_event` and `chat_deactivated`

Request

Parameter	Required	Type	Notes
`id`	Yes	`string`

No response payload.

Request

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

Response

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

Overview

Methods

List chats

List threads

Get chat

Start chat

Resume chat

Deactivate chat

​List chats

​List threads

​Get chat

​Start chat

​Resume chat

​Deactivate chat

List chats

List threads

Get chat

Start chat

Resume chat

Deactivate chat