Data structures

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, 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

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

Sample File in response

{
  "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
`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`	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
`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.

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",
  "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
`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
`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 for details.
`deleted`	optionally	Appears for deleted events, visible only to users with the `administrator` or `viceowner` role.

Sample Filled form in response

{
  "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
`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
`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",
  "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 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`.

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",
  "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 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.

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"
    }
  },
  "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
`visibility`	no	`string`	It can be specified when sending system messages via the 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

Sample System message in response

{
  "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. 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

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",
  "visibility": "all"
}

Users

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

Agent
- My profile
Customer

Agent

Field	Req./Opt.	Notes
`visibility`	required	Possible values: `all` or `agents`

Sample agent data structure

{
  "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.

Sample My profile data structure

{
  "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
`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/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": "<customer_ip>",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
    "geolocation": {
      "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"
  }
}

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
Form fields
Filled form fields
Properties
Threads
Deleted event

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.
`properties`	optional
`access`	optional

Sample Chat data structure

{
  "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": "<customer_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.

Sample Chat info data structure

{
  "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": "<customer_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 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	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`.
`next_accessible_thread_id`	optional	Present only if there is a following thread accessible for the requester. Field present only in `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).

Sample Thread data structure

{
  "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

Sample Deleted event in response

{
  "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"
}

Overview

Methods

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Agent

My profile

Customer

Other common structures

Access

Chats

Chat info

Form fields

Filled form fields

Properties

Threads

Deleted event

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​System

​Users

​Agent

​My profile

​Customer

​Other common structures

​Access

​Chats

​Chat info

​Form fields

​Filled form fields

​Properties

​Threads

​Deleted event

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Agent

My profile

Customer

Other common structures

Access

Chats

Chat info

Form fields

Filled form fields

Properties

Threads

Deleted event