> ## 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 Agent Chat API v3.7. This document contains a reference of data structures available in the Agent 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 The **File** event indicates about an uploaded file. **Request** | Parameter | Required | Data type | Notes | | ------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `custom_id` | no | `string` | | | `type` | yes | `string` | `file` | | `visibility` | no | `string` | Possible values: `all` (default), `agents` | | `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/agent-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 | | | `visibility` | 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 | | | `deleted` | optionally | Appears for deleted events, visible only to users with the `administrator` or `viceowner` role. | ```json Sample File in response theme={null} { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "file", "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z", "visibility": "all", "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 filled out by the customer. 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` | | `visibility` | no | `string` | Possible values: `all` (default), `agents` | | `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` | always | | | `visibility` | 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 | An array of [form fields](#form-fields) | | `deleted` | optionally | Appears for deleted events, visible only to users with the `administrator` or `viceowner` role. | **A sample use case:** sending a form in the chat after a pre-determined agent's inactivity period. This could be a way of gathering contact info from customers so that the overloaded agent can contact them later. ```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", "visibility": "all", "properties": { "property_namespace": { "property_name": "property_value" } }, "form_id": "1473433500211", "form_type": "prechat", "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 The **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` | | `visibility` | no | `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 | | | `visibility` | 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. | | `deleted` | optionally | Appears for deleted events, visible only to users with the `administrator` or `viceowner` role. | ```json Sample Filled form in response theme={null} { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "filled_form", "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z", "visibility": "all", "properties": { "property_namespace": { "property_name": "property_value" } }, "form_id": "1473433500211", "form_type": "prechat", "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 The **Message** event contains a 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` | | `visibility` | no | `string` | Possible values: `all` (default), `agents` | | `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 | | | `visibility` | 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", "type": "message", "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z", "text": "hello there", "postback": { "id": "action_call", "thread_id": "K600PKZON8", "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d", "type": "phone", "value": "790034890" }, "visibility": "all", "properties": { "property_namespace": { "property_name": "property_value" } } } ``` ### Rich message Rich message (RM) event contains a 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` | | `visibility` | no | `string` | Possible values: `all` (default), `agents` | | `properties` | no | `object` | The [properties](#properties) data structure | | `template_id` | yes | `string` | Defines how every Rich Message will be presented. Values: `cards`, `sticker`, `quick_replies` or `ecommerce`. | | `elements` | no | `array` | Can contain up to 10 `element` objects. | | `elements.title` | no | `string` | Displays formatted text on RMs. | | `elements.subtitle` | no | `string` | Displays formatted text on RMs. | | `elements.image` | no | `object` | 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`. | | `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`. | | `elements.ecommerce` | no | `object` | Should be used for the `ecommerce` template. Contains information about displayed product and its variants. | | `elements.ecommerce.view_type` | no | `string` | Defines how the product and its options are displayed. Possible values: `tags`, `swatch`, `images`, `select`. Required when sending `elements.ecommerce`. | | `elements.ecommerce.product_id` | no | `string` | Required when sending `elements.ecommerce`. | | `elements.ecommerce.label` | no | `string` | | | `elements.ecommerce.options` | no | `array` | An array of options for product. Required string params: `option_id`, `label`. Optional string params: `price`, `regular_price`, `currency`, `color`, `image_url`, `image_thumbnail_url`. Optional boolean params: `available`, `selected`. | | `elements.ecommerce.addons` | no | `array` | An array of addons for product. Required string param: `addon_type`. Optional string params: `range_from`, `range_to`, `currency`. | **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` | optionally | | | `elements.title` | optionally | | | `elements.subtitle` | optionally | | | `elements.image` | optionally | | | `elements.buttons` | optionally | | | `elements.buttons.text` | always | | | `elements.buttons.type` | always | | | `elements.buttons.value` | always | | | `elements.buttons.webview_height` | always | 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", "visibility": "all", "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 | | `visibility` | no | `string` | Possible values: `all` (default), `agents` | | `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 | | | `visibility` | always | | | `properties` | optionally | | | `deleted` | optionally | Appears for deleted events, visible only to users with the `administrator` or `viceowner` role. | ```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" } }, "visibility": "all", "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#system-messages) | | `visibility` | no | `string` | It can be specified when sending system messages via the [Send Event](#send-event) method. Possible values: `all`, `agents`. | | `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 | | | `visibility` | always | | ```json Sample System message in response theme={null} { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "system_message", "created_at": "2017-10-12T15:19:21.010200Z", "visibility": "all", "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 | System event source | | `type` | always | `system` | | `subtype` | always | System event subtype | | `version` | always | | | `details` | always | | | `created_at` | always | Date & time format with a resolution of microseconds, `UTC string`; generated server-side | | `visibility` | always | | ```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", "visibility": "all" } ``` ## Users **Users** are another important data structure. Within this data structure type, we can distinguish: * [Agent](#agent) * [My profile](#my-profile) * [Customer](#customer) ### Agent | Field | Req./Opt. | Notes | | ------------ | --------- | ---------------------------------- | | `visibility` | required | Possible values: `all` or `agents` | ```json Sample agent data structure theme={null} { "id": "smith@example.com", "type": "agent", "name": "Agent Smith", "email": "smith@example.com", "present": true, "events_seen_up_to": "2017-10-12T15:19:21.010200Z", "avatar": "cdn.livechatinc.com/avatars/1.png", "visibility": "all" } ``` #### My profile | Field | Req./Opt. | Notes | | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | `routing_status` | optional | | | `events_seen_up_to` | optional | RFC 3339 datetime string; the timestamp of the most recent event seen by the agent — all the previous events are considered seen. | ```json Sample My profile data structure theme={null} { "id": "smith@example.com", "type": "agent", "name": "Agent Smith", "email": "smith@example.com", "present": true, "events_seen_up_to": "2017-10-12T15:19:21.010200Z", "avatar": "cdn.livechatinc.com/avatars/1.png", "routing_status": "accepting_chats", "permission": "administrator" } ``` ### Customer | Field | Req./Opt. | Notes | | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | | `agent_last_event_created_at` | optional | | | `avatar` | optional | | | `customer_last_event_created_at` | optional | | | `created_at` | optional | | | `email` | optional | | | `email_verified` | optional | Specifies if the customer confirmed their email address. | | `session_fields` | optional | An array of custom object-enclosed key-value pairs. Expires along with the session. | | `name` | optional | | | `phone_number` | optional | | | `events_seen_up_to` | optional | RFC 3339 datetime string | | `visit` | optional | | | `present` | optional | | | `statistics` | optional | | | `omnichannel` | optional | | | `carts` | optional | An array of the customer's shopping carts. See [Cart](#cart) for the object structure. | | `address` | optional | An object of the customer's address data. | | `customer_properties` | optional | An object where keys are [customer property](#customer-property) IDs and values are their 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/avatars/1.png", "phone_number": "+18008529001", "visit": { "started_at": "2017-10-12T15:19:21.010200Z", "ended_at": "2017-10-12T15:21:01.000000Z", "referrer": "http://www.google.com/", "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": { "country": "Poland", "country_code": "PL", "region": "Dolnoslaskie", "city": "Wroclaw", "timezone": "Europe/Warsaw" }, "last_pages": [ { "opened_at": "2017-10-12T15:19:21.010200Z", "url": "https://www.text.com/", "title": "Text - Homepage" }, { "opened_at": "2017-10-12T15:19:21.010200Z", "url": "https://www.text.com/features/ai-agent/", "title": "Text - AI Agents" } ] }, "session_fields": [ { "custom_key": "custom_value" }, { "another_custom_key": "another_custom_value" } ], "statistics": { "chats_count": 3, "threads_count": 9, "visits_count": 5, "tickets_count": 12 }, "__priv_lc2_customer_id": "test_771305.dafea66e5c", "agent_last_event_created_at": "2017-10-12T15:19:21.010200Z", "customer_last_event_created_at": "2017-10-12T15:19:21.010200Z", "created_at": "2017-10-11T15:19:21.010200Z", "present": true, "events_seen_up_to": "2017-10-12T15:19:21.010200Z", "followed": false, "online": true, "group_ids": [0], "tickets": [ { "ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388", "created_at": "2017-10-12T15:19:21.010200Z" } ], "state": "browsing", "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" }, "customer_properties": { "550e8400-e29b-41d4-a716-446655440000": { "value": 42, "last_updated_at": "2026-06-11T12:00:00Z", "last_updated_agent_account_id": "464d206a-ba7d-4ce1-98d6-d03f8f14970e", "last_updated_agent_client_id": "71d32c598862b01b9e2298281339dbc2" } } } ``` ### Cart | Field | Data type | Notes | | -------------------- | ------------------ | --------------------------------------------------- | | `store_uuid` | `string` | The unique identifier of the store. | | `store_platform` | `string` | The platform of the store (for example, `shopify`). | | `customer_signed_in` | `bool` | Whether the customer is signed in. | | `subtotal` | `float` | Cart subtotal in the original currency. | | `total` | `float` | Cart total in the original currency. | | `subtotal_usd` | `float` | Cart subtotal converted to USD. | | `total_usd` | `float` | Cart total converted to USD. | | `currency` | `string` | The currency code (for example, `USD`, `EUR`). | | `items` | `array of objects` | An array of [Cart Item](#cart-item) objects. | | `last_updated_at` | `string` | RFC 3339 datetime string. | ### Cart Item | Field | Data type | Notes | | ------------ | --------- | ------------------------------------- | | `id` | `number` | The item ID. | | `quantity` | `number` | The quantity of the item in the cart. | | `variant_id` | `number` | The variant ID of the item. | ### Customer Property Customer properties are identified by the UUID generated in the [Create customer property definition](/api/customer-data-platform/customer-properties/create-customer-property-definition) method. The property's type is set on creation. | Field | Required | Data type | Notes | | ------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------ | | `value` | Yes | `any` | The current value of the property. The type is defined by the `CustomerPropertyType` enum. | | `last_updated_at` | Yes | `string` | RFC 3339 datetime string. | | `last_updated_agent_account_id` | No | `string` | Account ID of the agent that last set this value. | | `last_updated_agent_client_id` | No | `string` | Client ID of the application that last set this value. | ## 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) * [Form fields](#form-fields) * [Filled form fields](#filled-form-fields) * [Properties](#properties) * [Threads](#threads) * [Deleted event](#deleted-event) ### 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. | | | ------------ | :-------: | -: | | `properties` | optional | | | `access` | optional | | ```json Sample Chat data structure theme={null} { "id": "PJ0MRSHTDG", "threads": [ { "id": "QA37PVJ75B", "created_at": "2020-05-12T11:42:47.383000Z", "active": false, "user_ids": ["smith@example.com", "b7eff798-f8df-4364-8059-649c35c9ed0c"], "events": [ { "id": "QA37PVJ75B_1", "created_at": "2020-05-12T11:42:47.383001Z", "visibility": "all", "type": "filled_form", "properties": { "property_namespace": { "property_name": "property_value" } }, "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "custom_id": "gh4ocmtv83w", "form_id": "1002", "fields": [ { "id": "10021", "type": "name", "label": "Name and Surname:", "answer": "Thomas Anderson" }, { "id": "10022", "type": "email", "label": "E-mail:", "answer": "" } ] } ], "properties": { "property_namespace": { "property_name": "property_value" } }, "access": { "group_ids": [0] }, "tags": ["support", "positive feedback"], "previous_thread_id": "QA078URPJL" } ], "users": [ { "id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "name": "Thomas Anderson", "events_seen_up_to": "2020-05-12T12:31:46.463000Z", "type": "customer", "present": true, "created_at": "2019-11-02T19:19:50.625101Z", "visit": { "started_at": "2020-05-12T11:32:03.497479Z", "ended_at": "2020-05-12T11:33:33.497000Z", "ip": "", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36", "geolocation": { "country": "Poland", "country_code": "PL", "region": "Dolnoslaskie", "city": "Wroclaw", "timezone": "Europe/Warsaw", "latitude": "51.1043015", "longitude": "17.0335007" }, "last_pages": [ { "opened_at": "2020-05-12T11:32:03.497479Z", "url": "https://cdn.livechatinc.com/preview/11442778", "title": "Sample Page | Preview your chat window" } ] }, "statistics": { "chats_count": 1, "threads_count": 3, "visits_count": 6, "page_views_count": 2, "greetings_shown_count": 2, "greetings_accepted_count": 1, "tickets_count": 12 }, "agent_last_event_created_at": "2020-05-12T11:42:47.393002Z", "customer_last_event_created_at": "2020-05-12T12:31:46.463000Z", "tickets": [ { "ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388", "created_at": "2017-10-12T15:19:21.010200Z" } ] }, { "id": "smith@example.com", "name": "Agent Smith", "email": "smith@example.com", "events_seen_up_to": "2020-05-12T12:31:46.999999Z", "type": "agent", "present": false, "avatar": "https://cdn.livechat-files.com/api/file/avatar.png", "visibility": "all" } ], "properites": { "property_namespace": { "property_name": "property_value" } }, "access": { "group_ids": [1, 2] }, "is_followed": true } ``` ### 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": "QA37PVJ75B", "created_at": "2020-05-12T11:42:47.383000Z", "user_ids": ["smith@example.com", "b7eff798-f8df-4364-8059-649c35c9ed0c"], "properties": { "property_namespace": { "property_name": "property_value" } }, "active": false, "access": { "group_ids": [0] }, "queue": { "position": 42, "wait_time": 1337, "queued_at": "2020-05-12T11:42:47.383000Z" }, "last_event_per_type": { "message": { "event": { "id": "QA37PVJ75B_1", "created_at": "2020-05-12T11:42:47.383000Z", "type": "message", "properties": { "property_namespace": { "property_name": "property_value" } }, "text": "Hello", "author_id": "smith@example.com", "custom_id": "1589440960204.71699349177" } }, "system_message": { "event": { "id": "QA37PVJ75B_3", "created_at": "2020-05-12T12:31:46.563000Z", "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", "name": "Thomas Anderson", "events_seen_up_to": "2020-05-12T12:31:46.463000Z", "type": "customer", "present": true, "created_at": "2019-11-02T19:19:50.625101Z", "visit": { "started_at": "2020-05-12T11:32:03.497479Z", "ended_at": "2020-05-12T11:33:33.497000Z", "ip": "", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36", "geolocation": { "country": "Poland", "country_code": "PL", "region": "Dolnoslaskie", "city": "Wroclaw", "timezone": "Europe/Warsaw", "latitude": "51.1043015", "longitude": "17.0335007" }, "last_pages": [ { "opened_at": "2020-05-12T11:32:03.497479Z", "url": "https://cdn.livechatinc.com/preview/11442778", "title": "Sample Page | Preview your chat window" } ] }, "statistics": { "chats_count": 1, "threads_count": 3, "visits_count": 6, "page_views_count": 2, "greetings_shown_count": 2, "greetings_accepted_count": 1, "tickets_count": 12 }, "agent_last_event_created_at": "2020-05-12T11:42:47.393002Z", "customer_last_event_created_at": "2020-05-12T12:31:46.463000Z", "tickets": [ { "ticket_id": "0c04cb99-817a-4935-9d62-137c89a74388", "created_at": "2017-10-12T15:19:21.010200Z" } ] }, { "id": "smith@example.com", "name": "Agent Smith", "email": "smith@example.com", "events_seen_up_to": "2020-05-12T12:31:46.999999Z", "type": "agent", "present": false, "avatar": "https://cdn.livechat-files.com/api/file/avatar.png" } ], "properites": { "property_namespace": { "property_name": "property_value" } }, "access": { "group_ids": [0] }, "is_followed": false } ``` ### 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 | Doesn't exist if `restricted_access` is present. | | `properties` | optional | | | `restricted_access` | optional | Contains the reason for access restriction. | | `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. | | `previous_accessible_thread_id` | optional | Present only if there is a preceding thread accessible for the requester. Field present only in [`list_archives`](#list-archives). | | `next_accessible_thread_id` | optional | Present only if there is a following thread accessible for the requester. Field present only in [`list_archives`](#list-archives). | | `created_at` | required | Date & time format with a resolution of microseconds, `UTC string`. Generated server-side. | | `tags` | optional | An array of tags. Returned only if a thread was tagged. | | `customer_visit` | optional | Contains details about customer visit (IP, User agent and geolocation). | ```json Sample Thread data structure theme={null} { "id": "K600PKZON8", "active": true, "user_ids": ["smith@example.com"], "restricted_access": "You can't access threads older than 60 days on starter plan", "events": [ { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "message", "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z", "text": "Hello there", "visibility": "all" }, { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "message", "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z", "text": "Thank you", "visibility": "all" } ], "properties": { "property_namespace": { "property_name": "property_value" } }, "access": { "group_ids": [1, 2] }, "tags": ["sales"], "queue": { "position": 42, "wait_time": 1337, "queued_at": "2020-05-07T07:11:28.288340Z" }, "queues_duration": 1337, "previous_thread_id": "K600PKZOM8", "next_thread_id": "K600PKZOO8", "created_at": "2020-05-07T07:11:28.288340Z" } ``` ### Deleted event The **Deleted Event** is returned to agents with the `normal` role in place of the original event. | Field | Returned | Notes | | ------------ | ---------- | ------------------------------------------------------------------- | | `id` | always | | | `created_at` | always | Date & time format with a resolution of microseconds, `UTC string`. | | `type` | always | The original event type. | | `visibility` | always | | | `deleted` | always | | | `author_id` | optionally | | | `custom_id` | optionally | | ```json Sample Deleted event in response theme={null} { "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", "custom_id": "31-0C-1C-07-DB-16", "type": "message", "deleted": true, "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", "created_at": "2017-10-12T15:19:21.010200Z" } ```