Data structures

This document contains a reference of data structures available in the Customer Chat API. Here, you can review the object fields, as well as sample responses for the event, user, and other common structures. The reference applies both to the Web and RTM APIs.

Events

One of the data structures are events. They are sent to a chat via the send_event method. Apart from events, there are also Properties, Users, and Other common data structures. These are the available event types:

File
Form
Filled form
Message
Rich message
Custom
System message
System

File

File event indicates about a file being uploaded. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the Text CDN. It’s recommended to use the URL returned by `upload_file`.
`alternative_text`	no	`string`	Only applicable to images

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`properties`	optionally
`name`	always
`url`	always
`thumbnail_url`, `thumbnail2x_url`	only for images
`content_type`	always
`size`, `width`, `height`	only for images
`alternative_text`	only for images

Sample File in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "file",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "name": "image25.png",
  "url": "https://example.com/image25.png",
  "thumbnail_url": "https://example.com/thumbnail.png",
  "thumbnail2x_url": "https://example.com/thumbnail2x.png",
  "content_type": "image/png",
  "size": 123444,
  "width": 640,
  "height": 480,
  "alternative_text": "A sample image"
}

Form

The Form event contains an empty form to be sent in the chat. It doesn’t matter how the form is configured or what fields it has — it can be any event of type form. Currently, the Form events are not supported natively in Text, but you can leverage this feature in a custom chatting solution. Request

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`form`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	optionally	If form is generated by `system`, then this field is omitted.
`properties`	optionally
`form_id`	always
`form_type`	optionally	The most popular form types include: `prechat`, `postchat`, `ask_for_email`, but those aren’t the only possible options. If you don’t see this field in a chat, it means that chat had been started before we introduced this field.
`fields`	always	An array of form fields

Sample Form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "required": true
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "required": false
    },
    {
      "type": "question",
      "id": "154417206262601585",
      "label": "What are you looking for?",
      "required": false
    },
    {
      "type": "textarea",
      "id": "154417206262601586",
      "label": "Additional info",
      "required": false
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "Support"
        }
      ]
    },
    {
      "type": "select",
      "id": "154417206262602572",
      "label": "Country",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "USA"
        },
        {
          "id": "1",
          "label": "UK"
        }
      ]
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    }
  ]
}

Filled form

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

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`filled_form`
`recipients`	yes	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See filled form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`properties`	optionally
`form_id`	always
`form_type`	optionally	The most popular form types include: `prechat`, `postchat`, `ask_for_email`, but those aren’t the only possible options. If you don’t see this field in a chat, it means that chat had been started before we introduced this field.
`fields`	always	The fields a form contains. See filled form fields for details.

Sample Filled form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "filled_form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "answer": "Thomas Anderson"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "answer": "t.anderson@example.com"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "answer": {
        "id": "0",
        "label": "Support"
      }
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "answers": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department",
      "answer": {
        "id": "2",
        "group_id": 1,
        "label": "Marketing"
      }
    }
  ]
}

Message

Message event contains text message to other chat users. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`text`	yes	`string`	Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
`type`	yes	`string`	`message`
`properties`	no	`object`	Properties
`postback`	no	`object`	Indicates that the message event was generated in response to a rich message event.
`postback.id`	yes	`string`	ID of the postback from the rich message event.
`postback.thread_id`	yes	`string`	ID of the thread with the rich message event.
`postback.event_id`	yes	`string`	ID of the rich message event.
`postback.type`	no	`string`	Should be used together with `postback.value` (when one of them is present, the other is required).
`postback.value`	no	`string`	Should be used together with `postback.type` (when one of them is present, the other is required).
`postback.ecommerce`	no	`object`	Object containing data specific to rich messages with `ecommerce` template, like `product_id`.
`postback.ecommerce.product_id`	no	`string`	The ID of the product displayed by the rich message. Required when sending `postback.ecommerce`.
`postback.ecommerce.option_id`	no	`string`	The ID of the selected option for the product.
`postback.ecommerce.quantity`	no	`number`	Quantity of the product.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always	`message`
`author_id`	always
`text`	always
`postback`	optionally	Appears in a message only when triggered by a rich message.
`postback.id`	always
`postback.thread_id`	always
`postback.event_id`	always
`postback.type`	optionally	Appears only if `postback.value` is present.
`postback.value`	optionally	Appears only if `postback.type` is present.
`postback.ecommerce`	optionally
`postback.ecommerce.product_id`	optionally
`postback.ecommerce.option_id`	optionally
`postback.ecommerce.quantity`	optionally
`properties`	optionally	Properties
`deleted`	optionally	Appears for deleted events, visible only to users with the `administrator` or `viceowner` role.

Sample Message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  }
}

Rich message

Rich message event contains rich message data structure. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give your RM a custom ID.
`type`	yes	`string`	Event type: `rich_message`
`properties`	no	`object`	The properties data structure
`template_id`	yes	`string`	Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`.
`elements`	no	`array`	Can contain up to 10 `element` objects.
`elements.title`	yes	`string`	Displays formatted text on RMs.
`elements.subtitle`	yes	`string`	Displays formatted text on RMs.
`elements.image`	yes	`image`	Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `alternative_text`.
`elements.buttons`	no	`array`	Displays buttons. Can contain up to 13 `button` objects.
`elements.buttons.text`	yes	`string`	Text displayed on a button.
`elements.buttons.type`	yes	`string`	Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`.
`elements.buttons.value`	yes	`string`	Should be used together with `elements.buttons.type`. You can use this field to give the rich message of a `webview` type (a Moment) a custom title.
`elements.buttons.webview_height`	yes	`string`	Required only for the `webview` button `type`. Possible values: `compact`, `full`, `tall`.
`elements.buttons.postback_id`	yes	`string`	A description of the sent action. Describes the action sent via `send_rich_message_postback`.
`elements.buttons.user_ids`	yes	`array`	Describes users that sent the postback with `"toggled": true`.
`elements.buttons.target`	no	`string`	Should be used for the `url` button `type`. Specifies if the URL should open in the current or a new tab. Possible values: `new`, `current`.

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.
`visibility`	always
`properties`	optionally
`template_id`	always
`elements`	always
`elements.title`	optionally
`elements.subtitle`	optionally
`elements.image`	optionally	When present contains param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `alternative_text`
`elements.buttons`	optionally
`elements.buttons.text`	always
`elements.buttons.type`	always
`elements.buttons.value`	always
`elements.buttons.webview_height`	optionally	Unless button `type` is different than `webview`.
`elements.buttons.postback_id`	always
`elements.buttons.user_ids`	always
`elements.buttons.target`	optionally
`elements.ecommerce`	optionally	This element is only present for rich messages with `template_id` set to `ecommerce`.
`elements.ecommerce.view_type`	optionally	Can be either `tags`, `swatch`, `images` or `select`.
`elements.ecommerce.product_id`	optionally
`elements.ecommerce.label`	optionally
`elements.ecommerce.options`	optionally	Each option consists of `option_id`, `label` and optionally `price`, `regular_price`, `currency`, `color`, `image_url`, `image_thumbnail_url`, `available`, `selected`.
`elements.ecommerce.addons`	optionally	Each addon consists of `addon_type` and optionally `range_from`, `range_to`, `currency`.

Sample Rich message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "rich_message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "template_id": "cards",
  "elements": [
    {
      "title": "Lorem ipsum dolor.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "image": {
        "name": "image25.png",
        "url": "https://example.com/image25.png",
        "content_type": "image/png",
        "size": 123444,
        "width": 640,
        "height": 480,
        "alternative_text": "A picture of lorem ipsum"
      },
      "buttons": [
        {
          "text": "yes",
          "postback_id": "action_yes",
          "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
        },
        {
          "text": "no",
          "postback_id": "action_no",
          "user_ids": []
        },
        {
          "type": "phone",
          "text": "value",
          "value": "790034890",
          "webview_height": "tall",
          "postback_id": "action_call",
          "user_ids": [],
          "target": "current"
        }
      ]
    }
  ]
}

Custom

Custom event is an event with customizable payload. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the event a custom ID.
`type`	yes	`string`	Event type: `custom`
`content`	no	`object`	The content you define
`properties`	no	`object`	The properties data structure

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`content`	optionally
`properties`	optionally

Sample Custom event in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "custom",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "content": {
    "custom": {
      "nested": "json"
    }
  },
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  }
}

System message

System message event is a native system event sent in specific situations. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the system message a custom ID.
`type`	yes	`string`	`system_message`
`text`	no	`string`	Text displayed to recipients
`system_message_type`	yes	`string`	System message type
`text_vars`	no	`object`	Variables used in the text

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`text`	optionally
`system_message_type`	always

Sample System message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "system_message",
  "text": "hello there",
  "system_message_type": "routing.assigned",
  "text_vars": {
    "agent": "John Doe"
  }
}

System

System event is an extension and a future replacement for System message. Similarly, it is a native system event sent in specific situations. Request It is not possible to send a System event in API version 3.7. Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`source`	always
`type`	always
`subtype`	always
`version`	always
`details`	always
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side

Sample System event in response

{
  "id": "17f5ac89-e578-4d3f-9ab9-675be6209b00",
  "custom_id": "shopify_1744119867",
  "source": "cdp",
  "type": "system",
  "subtype": "store_order_was_created",
  "version": 1,
  "details": "{\"store\":{\"id\":\"my-store\",\"platform\":\"shopify\",\"uuid\":\"70cb9e59-b639-41c5-81cf-71db11972cff\",\"url\":\"https://my-store.myshopify.com\",\"name\":\"My Store\"},\"order\":{\"id\":\"gid://shopify/Order/1234567890\",\"order_number\":\"#1001\",\"currency\":\"USD\",\"total_price\":123.45,\"line_items\":[{\"title\":\"Product Name\",\"quantity\":2,\"price\":49.99,\"sku\":\"SKU123\",\"variant_id\":\"gid://shopify/ProductVariant/12345678901234\"}]}}",
  "created_at": "2017-10-12T15:19:21.010200Z"
}

Users

Users are another important data structure. Within this data structure type, we can distinguish:

Customer
Agent

Customer

Field	Req./Opt.	Notes
`avatar`	optional
`email`	optional
`email_verified`	optional	Specifies if the customer confirmed their email address.
`name`	optional
`phone_number`	optional
`session_fields`	optional	An array of custom object-enclosed key-value pairs. Available for the session duration.
`omnichannel`	optional	An object of the customer’s omnichannel data.
`address`	optional	An object of the customer’s address data.

Sample Customer data structure

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "email_verified": false,
  "avatar": "https://example.com/avatar.png",
  "phone_number": "+18008529001",
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ],
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "omnichannel": {
    "fbmessenger": [
      {
        "id": "fb_messenger_id",
        "name": "Thomas Anderson",
        "first_name": "Thomas",
        "last_name": "Anderson",
        "profile_pic": "https://example.com/avatars/1.png",
        "gender": "male",
        "locale": "en_US",
        "is_verified_user": true
      }
    ],
    "twilio": [
      {
        "+18008529001": {
          "phone_number": "+18008529001"
        }
      }
    ],
    "whatsapp": [
      {
        "id": "15550001234",
        "name": "Thomas Anderson",
        "phone_number": "+15550001234"
      }
    ]
  },
  "address": {
    "address": "1600 Pennsylvania Avenue NW",
    "city": "Washington",
    "country": "United States",
    "state": "DC",
    "postal_code": "20500"
  }
}

Agent

Sample Agent data structure

{
  "id": "b5657aff34dd32e198160d54666df9d8",
  "type": "agent",
  "name": "Agent Smith",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}

Other common structures

Apart from Events and Users, there are also other common data structures you might work with. Those are:

Access
Chats
Chat info
Forms
Form fields
Filled form fields
Properties
Threads

Access

Field	Req./Opt.	Note
`group_ids`	required	`group 0` means that all agents can see it.

Sample Access data structure

{
  "access": {
    "group_ids": [1, 2]
  }
}

Chats

Field	Req./Opt.	Note
`properties`	optional
`access`	optional

Sample Chat data structure

{
  "id": "PJ0MRSHTDG",
  "threads": [
    {
      "id": "QA1B38GHGI",
      "created_at": "2020-05-07T07:11:28.288340Z",
      "active": false,
      "user_ids": [
        "bbb67d600796e9f277e360e842418833",
        "b7eff798-f8df-4364-8059-649c35c9ed0c"
      ],
      "events": [
        {
          "id": "QA1B38GHGI_1",
          "created_at": "2020-05-14T07:22:40.269000Z",
          "type": "message",
          "properties": {
            "source": {
              "client_id": "0805e283233042b37f460ed8fbf22160"
            }
          },
          "text": "hello",
          "author_id": "bbb67d600796e9f277e360e842418833",
          "custom_id": "1589440960204.71699349177"
        },
        {
          "id": "QA1B38GHGI_3",
          "created_at": "2020-05-14T08:18:44.015000Z",
          "type": "system_message",
          "text": "The chat was closed because Agent Smith had lost internet connection",
          "system_message_type": "routing.archived_disconnected",
          "text_vars": {
            "agent": "Agent Smith"
          }
        }
      ],
      "properites": {
        "property_namespace": {
          "property_name": "property_value"
        }
      },
      "access": {
        "group_ids": [0]
      },
      "previous_thread_id": "K600PKZOM8",
      "next_thread_id": "K600PKZOO8"
    }
  ],
  "users": [
    {
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "type": "customer",
      "present": true
    },
    {
      "id": "bbb67d600796e9f277e360e842418833",
      "name": "Agent Smith",
      "events_seen_up_to": "2020-05-14T07:22:37.287496Z",
      "type": "agent",
      "present": false,
      "avatar": "https://cdn.livechat-files.com/api/file/avatar.png",
      "job_title": "Support Agent"
    }
  ],
  "access": {
    "group_ids": [0]
  },
  "properites": {
    "property_namespace": {
      "property_name": "property_value"
    }
  }
}

Chat info

Chat info is similar to the Chat data structure. The difference is that Chat contains a thread object, while Chat info includes last_thread_info.

Sample Chat info data structure

{
  "id": "PJ0MRSHTDG",
  "last_thread_info": {
    "id": "QA1B38GHGI",
    "created_at": "2020-05-08T08:22:21.128420Z",
    "last_event_per_type": {
      "message": {
        "event": {
          "id": "QA1B38GHGI_1",
          "created_at": "2020-05-14T07:22:40.269000Z",
          "type": "message",
          "properties": {
            "property_namespace": {
              "property_name": "property_value"
            }
          },
          "text": "Hello",
          "author_id": "bbb67d600796e9f277e360e842418833",
          "custom_id": "1589440960204.71699349177"
        }
      },
      "system_message": {
        "event": {
          "id": "QA1B38GHGI_3",
          "created_at": "2020-05-14T08:18:44.015000Z",
          "type": "system_message",
          "text": "The chat was closed because Agent Smith had lost internet connection",
          "system_message_type": "routing.archived_disconnected",
          "text_vars": {
            "agent": "Agent Smith"
          }
        }
      }
    }
  },
  "users": [
    {
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "type": "customer",
      "present": true
    },
    {
      "id": "bbb67d600796e9f277e360e842418833",
      "name": "Agent Smith",
      "events_seen_up_to": "2020-05-14T07:22:37.287496Z",
      "type": "agent",
      "present": false,
      "avatar": "https://cdn.livechat-files.com/api/file/avatar.png",
      "job_title": "Support Agent"
    }
  ],
  "properites": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "active": false
}

Forms

A template of a prechat, postchat, or a ticket form.

Field	Required	Data type	Notes
`id`	no	`string`	Form ID
`fields`	yes	`array of objects`	The fields a form contains
`fields.type`	yes	`string`	Possible values: `header`, `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`fields.id`	no	`string`	Field ID, for all field types
`fields.label`	yes	`string`	Field label, for all field types
`fields.required`	no	`bool`	Determines whether the answer for given field is required, for all field types except `header`
`fields.options`	no	`array of objects`	For `checkbox`, `group_chooser`, `radio` and `select`
`fields.options.id`	yes	`string`	An identifier of each option a customer can choose
`fields.options.label`	yes	`string`	Answer label
`fields.options.group_id`	yes	`number`	For `group_chooser`

Sample Form data structure

{
  "id": "157986144052005549",
  "fields": [
    {
      "id": "157986144052003238",
      "type": "header",
      "label": "Welcome to our chat! 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"
        }
      ]
    }
  ]
}

Form fields

A component of the Form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types

Sample Form fields

{
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose"
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry"
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department"
    }
  ]
}

Filled form fields

A component of the Filled form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types
`answer`	yes	`any`	For all field types
`answer.id`	yes	`string`	An identifier of each option a customer can choose. For all field types.
`answer.label`	yes	`string`	Answer label; for all field types
`answer.group_id`	yes	`number`	For `group_chooser`

Sample Filled form fields

{
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "answer": "Thomas Anderson"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "answer": "t.anderson@example.com"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "answer": {
        "id": "0",
        "label": "Support"
      }
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "answers": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department",
      "answer": {
        "id": "2",
        "group_id": 1,
        "label": "Marketing"
      }
    }
  ]
}

Properties

Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.

Sample Properties data structure

{
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "string value"
    }
  }
}

Threads

Field	Req./Opt.	Note
`access`	optional
`active`	required	Possible values: `true` (thread is still active) or `false` (thread no longer active).
`events`	optional
`properties`	optional
`queue`	optional	Present only if the chat is in the queue. The wait time for an available agent is approximated in seconds.
`previous_thread_id`	optional	Present only if there is a preceding thread.
`next_thread_id`	optional	Present only if there is a following thread.
`created_at`	required	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.

Sample Thread data structure

{
  "id": "K600PKZON8",
  "active": true,
  "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"],
  "events": [
    {
      "id": "QA1B38GHGI_1",
      "created_at": "2020-05-14T07:22:40.269000Z",
      "type": "message",
      "properties": {
        "property_namespace": {
          "property_name": "property_value"
        }
      },
      "text": "hello",
      "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "custom_id": "1589440960204.71699349177"
    }
  ],
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "queue": {
    "position": 42,
    "wait_time": 1337,
    "queued_at": "2020-05-07T07:11:28.288340Z"
  },
  "previous_thread_id": "K600PKZOM8",
  "next_thread_id": "K600PKZOO8",
  "created_at": "2020-05-07T07:11:28.288340Z"
}

Overview

Methods

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Customer

Agent

Other common structures

Access

Chats

Chat info

Forms

Form fields

Filled form fields

Properties

Threads

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​System

​Users

​Customer

​Agent

​Other common structures

​Access

​Chats

​Chat info

​Forms

​Form fields

​Filled form fields

​Properties

​Threads

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Customer

Agent

Other common structures

Access

Chats

Chat info

Forms

Form fields

Filled form fields

Properties

Threads