> ## 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. # Data structures > Reference of data structures available in the Customer Chat API v3.7. 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](#events), [user](#users), and [other common structures](#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](#properties), [Users](#users), and [Other common data structures](#other-common-structures). These are the available **event types**: * [File](#file) * [Form](#form) * [Filled form](#filled-form) * [Message](#message) * [Rich message](#rich-message) * [Custom](#custom) * [System message](#system-message) * [System](#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](#properties) | | `url` | yes | `string` | Has to point to the Text CDN. It's recommended to use the URL returned by [`upload_file`](/api/customer-chat/v3.7/events/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 | | ```json Sample File in response theme={null} { "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](#properties) | | `form_id` | yes | `string` | | | `fields` | yes | `array` | The fields a form contains. See [form fields](#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](#form-fields) | ```json Sample Form in response theme={null} { "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](#properties) | | `form_id` | yes | `string` | | | `fields` | yes | `array` | The fields a form contains. See [filled form fields](#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](#filled-form-fields) for details. | ```json Sample Filled form in response theme={null} { "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](#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](#properties) | | `deleted` | optionally | Appears for deleted events, visible only to users with the `administrator` or `viceowner` role. | ```json Sample Message in response theme={null} { "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](#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`. | ```json Sample Rich message in response theme={null} { "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](#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 | | ```json Sample Custom event in response theme={null} { "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](/api/events-and-properties/system-activities) | | `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 | | ```json Sample System message in response theme={null} { "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](#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 | ```json Sample System event in response theme={null} { "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](#customer) * [Agent](#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. | ```json Sample Customer data structure theme={null} { "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 ```json Sample Agent data structure theme={null} { "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](#events) and [Users](#users), there are also other common data structures you might work with. Those are: * [Access](#access) * [Chats](#chats) * [Chat info](#chat-info) * [Forms](#forms) * [Form fields](#form-fields) * [Filled form fields](#filled-form-fields) * [Properties](#properties) * [Threads](#threads) ### Access | Field | Req./Opt. | Note | | ----------- | :-------: | ------------------------------------------- | | `group_ids` | required | `group 0` means that all agents can see it. | ```json Sample Access data structure theme={null} { "access": { "group_ids": [1, 2] } } ``` ### Chats | Field | Req./Opt. | Note | | ------------ | :-------: | ---: | | `properties` | optional | | | `access` | optional | | ```json Sample Chat data structure theme={null} { "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`. ```json Sample Chat info data structure theme={null} { "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` | ```json Sample Form data structure theme={null} { "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](#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 | ```json Sample Form fields theme={null} { "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](#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` | ```json Sample Filled form fields theme={null} { "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](/api/configuration/v3.7/) document. ```json Sample Properties data structure theme={null} { "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. | ```json Sample Thread data structure theme={null} { "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" } ```