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

Events are sent to a chat through the send_event method.

File

The File event indicates about an uploaded file.

Request

string

The custom event ID.

string

required

The event type. Must be file.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The file URL. It must point to the Text CDN. Use the URL returned by upload_file.

string

The alternative text for an image.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event creation timestamp in UTC with microsecond precision.

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The file name.

string

required

The file URL.

string

images only

The image thumbnail URLs.

string

required

The file media type.

integer

images only

The file size and image dimensions.

string

images only

The alternative text for the image.

boolean

If true, the event is deleted. This field is 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",
  "deleted": false
}

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

string

The custom event ID.

string

required

The event type. Must be form.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The form ID.

array

required

The fields in the form. See Form fields.

Show fields properties

string

required

The form field type. Possible values: checkbox, date, email, group_chooser, name, phone, question, radio, select, subject, textarea.

string

required

The form field ID. The value must be unique within the form.

string

required

The form field label.

boolean

If true, the customer must complete the field before submitting the form.

string

The ID of the customer property updated when the customer submits the form.

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event creation timestamp in RFC 3339 format with microsecond precision.

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The form ID.

string

The form type. Common values include prechat, postchat, and ask_for_email. This field is absent from chats started before the field was introduced.

array

required

The fields in the form. See Form fields.

Show fields properties

string

required

The form field type.

string

required

The form field ID.

string

required

The form field label.

boolean

If true, the customer must complete the field before submitting the form.

string

The ID of the customer property updated when the customer submits the form.

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

boolean

If true, the event is deleted. This field is 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,
      "customer_property_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "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"
        }
      ]
    }
  ],
  "deleted": false
}

Filled form

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

Request

string

The custom event ID.

string

required

The event type. Must be filled_form.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The form ID.

array

required

The completed form fields. See Filled form fields.

Show fields properties

string

required

The form field type. Possible values: checkbox, date, email, group_chooser, name, phone, question, radio, select, subject, textarea.

string

required

The form field ID. The value must be unique within the form.

string

required

The form field label.

any

The submitted answer. Its type depends on fields.type.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID. This field is required when fields.type is group_chooser.

array

The submitted checkbox answers.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event creation timestamp in RFC 3339 format with microsecond precision.

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The form ID.

string

The form type. Common values include prechat, postchat, and ask_for_email. This field is absent from chats started before the field was introduced.

array

required

The completed form fields. See Filled form fields.

Show fields properties

string

required

The form field type.

string

required

The form field ID.

string

required

The form field label.

string | object | boolean

The submitted answer. Its type depends on fields.type.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID. This field is returned when fields.type is group_chooser.

array

The submitted checkbox answers.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

boolean

If true, the event is deleted. This field is 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"
      }
    }
  ],
  "deleted": false
}

Message

The Message event contains a text message to other chat users.

Request

string

The custom event ID.

string

required

The message text. The raw text can be up to 16 KB. A single UTF-8 character can use up to 4 bytes. Split longer text into multiple messages.

string

required

The event type. Must be message.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

object

The postback that generated the message in response to a rich message.

Show postback properties

string

required

The postback ID from the rich message event.

string

required

The ID of the thread containing the rich message event.

string

required

The ID of the rich message event.

string

The postback type. If this field is provided, postback.value is also required.

string

The postback value. If this field is provided, postback.type is also required.

object

The e-commerce data associated with the rich message postback.

Show postback.ecommerce properties

string

required

The ID of the product displayed in the rich message.

string

The ID of the selected product option.

integer

The product quantity.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event creation timestamp in RFC 3339 format with microsecond precision.

string

required

The event type. Always message.

string

required

The ID of the event author.

string

required

The event visibility.

string

required

The message text.

object

The rich message postback that triggered the message.

Show postback properties

string

required

The postback ID from the rich message event.

string

required

The ID of the thread containing the rich message event.

string

required

The ID of the rich message event.

string

The postback type. This field is returned when postback.value is present.

string

The postback value. This field is returned when postback.type is present.

object

The e-commerce data associated with the rich message postback.

Show postback.ecommerce properties

string

required

The ID of the product displayed in the rich message.

string

The ID of the selected product option.

integer

The product quantity.

object

Custom event properties organized by namespace and property name. See Properties.

boolean

If true, the event is deleted. This field is 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",
    "ecommerce": {
      "product_id": "prod123",
      "option_id": "opt1",
      "quantity": 1
    }
  },
  "visibility": "all",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "deleted": false
}

Rich message

Rich message (RM) event contains a rich message data structure.

Request

string

The custom event ID.

string

required

The event type. Must be rich_message.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The template that determines how the rich message is displayed. Possible values: cards, sticker, quick_replies, ecommerce.

array

An array of up to 10 rich message elements.

Show elements properties

string

The formatted title of the rich message element.

string

The formatted subtitle of the rich message element.

object

The image displayed in the rich message element.

Show elements.image properties

string

The image file name.

string

required

The image URL.

string

The image media type.

integer

The image width in pixels.

integer

The image height in pixels.

integer

The image file size in bytes.

string

The alternative text for the image.

array

An array of up to 13 buttons displayed in the rich message element.

Show elements.buttons properties

string

required

The text displayed on the button.

string

The behavior after a user selects the button. If this field is provided, elements.buttons.value is also required. Possible values: webview, message, url, phone.

string

The button value. If this field is provided, elements.buttons.type is also required.

string

The webview height. Required when type is webview. Possible values: compact, full, tall.

string

required

The identifier that describes the action sent by send_rich_message_postback.

array

required

The IDs of users who sent the postback with "toggled": true.

string

The browsing context in which to open the URL. Applies when type is url. Possible values: new, current.

object

The product and product variant information. Applies when template_id is ecommerce.

Show elements.ecommerce properties

string

required

The presentation of the product and its options. Possible values: tags, swatch, images, select.

string

required

The product ID.

string

The product label.

array

An array of up to 10 product options.

Show elements.ecommerce.options properties

string

required

The product option ID.

string

required

The product option label.

string

The product option price.

string

The regular product option price.

string

The currency of the product option price.

string

The product option color. Required when view_type is swatch.

string

The product option image URL. Required when view_type is images.

string

The product option thumbnail URL.

boolean

If true, the product option is available.

boolean

If true, the product option is selected.

array

An array of up to 10 product add-ons.

Show elements.ecommerce.addons properties

string

required

The product add-on type.

string

The start of the product add-on price range.

string

The end of the product add-on price range.

string

The currency of the product add-on price range.

Response

string

required

The server-generated event ID.

string

The custom event ID.

string

required

The event type.

string

required

The server-generated ID of the event author.

string

required

The server-generated event creation timestamp in UTC with microsecond precision.

string

required

The event visibility.

object

Custom event properties organized by namespace and property name. See Properties.

string

required

The template that determines how the rich message is displayed.

array

required

The rich message elements.

Show elements properties

string

The formatted title of the rich message element.

string

The formatted subtitle of the rich message element.

object

The image displayed in the rich message element.

Show elements.image properties

string

The image file name.

string

required

The image URL.

string

The image media type.

integer

The image width in pixels.

integer

The image height in pixels.

integer

The image file size in bytes.

string

The alternative text for the image.

array

The buttons displayed in the rich message element.

Show elements.buttons properties

string

required

The text displayed on the button.

string

The behavior after a user selects the button. This field is returned with elements.buttons.value.

string

The button value. This field is returned with elements.buttons.type.

string

The webview height. Present when type is webview.

string

required

The identifier that describes the postback action.

array

required

The IDs of users who sent the postback with "toggled": true.

string

The browsing context in which to open the URL.

object

The product and product variant information. Present when template_id is ecommerce.

Show elements.ecommerce properties

string

required

The presentation of the product and its options. Possible values: tags, swatch, images, select.

string

required

The product ID.

string

The product label.

array

The product options.

Show elements.ecommerce.options properties

string

required

The product option ID.

string

required

The product option label.

string

The product option price.

string

The regular product option price.

string

The currency of the product option price.

string

The product option color.

string

The product option image URL.

string

The product option thumbnail URL.

boolean

If true, the product option is available.

boolean

If true, the product option is selected.

array

The product add-ons.

Show elements.ecommerce.addons properties

string

required

The product add-on type.

string

The start of the product add-on price range.

string

The end of the product add-on price range.

string

The currency of the product add-on price range.

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": "ecommerce",
  "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"
        }
      ],
      "ecommerce": {
        "view_type": "tags",
        "product_id": "prod123",
        "label": "Sample product",
        "options": [
          {
            "option_id": "opt1",
            "label": "Black",
            "price": "100",
            "regular_price": "120",
            "currency": "USD",
            "color": "#000000",
            "image_url": "https://example.com/product-black.png",
            "image_thumbnail_url": "https://example.com/product-black-thumbnail.png",
            "available": true,
            "selected": true
          }
        ],
        "addons": [
          {
            "addon_type": "warranty",
            "range_from": "10",
            "range_to": "20",
            "currency": "USD"
          }
        ]
      }
    }
  ]
}

Custom

Custom event is an event with customizable payload.

Request

string

The custom event ID.

string

required

The event type. Must be custom.

object

The custom JSON content.

string

default:"all"

The event visibility. Possible values: all, agents.

object

Custom event properties organized by namespace and property name. See Properties.

Response

string

required

The event ID generated by the server.

string

The custom event ID.

string

required

The event type.

string

required

The ID of the event author generated by the server.

string

required

The event creation timestamp generated by the server in RFC 3339 format with microsecond precision.

object

The custom JSON content.

string

required

The event visibility.

object

Custom event properties organized by namespace and property name. See Properties.

boolean

If true, the event is deleted. This field is 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"
    }
  },
  "deleted": false
}

System message

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

Request

string

The custom event ID.

string

required

The event type. Must be system_message.

string

The text displayed to recipients.

string

required

The system message type. See System message types.

string

default:"agents"

The event visibility. Possible values: all, agents.

object

The variables substituted into the system message text.

Response

string

required

The event ID generated by the server.

string

The custom event ID.

string

required

The event type.

string

required

The event creation timestamp generated by the server in RFC 3339 format with microsecond precision.

string

The text displayed to recipients.

string

required

The system message type. See System message types.

string

required

The event visibility.

object

The variables substituted into the system message text.

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

string

required

The event ID generated by the server.

string

The custom event ID.

string

required

The system event source.

string

required

The event type. Always system.

string

required

The system event subtype.

integer

required

The system event schema version.

string

required

The JSON-encoded event details.

string

required

The event creation timestamp generated by the server in RFC 3339 format with microsecond precision.

string

required

The event visibility.

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 represent agents and customers participating in chats.

Agent

Fields

string

required

The agent ID.

string

required

The user type. Always agent.

string

The agent’s name.

string

The agent’s email address.

boolean

If true, the agent is present in the chat.

string

The timestamp of the most recent event seen by the agent, in RFC 3339 format. All earlier events are considered seen.

string

required

The URL of the agent’s avatar.

string

required

The agent’s visibility. Possible values: all, 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

Fields

string

required

The agent ID.

string

required

The user type. Always agent.

string

The agent’s name.

string

The agent’s email address.

boolean

If true, the agent is present in the chat.

string

required

The URL of the agent’s avatar.

string

The agent’s routing status. Possible values: accepting_chats, not_accepting_chats, offline. The offline value applies only to bot agents.

string

The timestamp of the most recent event seen by the agent, in RFC 3339 format. All earlier events are considered seen.

string

required

The agent’s role. Possible values: normal, administrator, viceowner, owner.

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

Fields

string

required

The customer ID.

string

required

The user type. Always customer.

string

The date and time of the last event created by an agent in the customer’s chats.

string

The URL of the customer’s avatar.

string

The date and time of the last event created by the customer.

string

The date and time when the customer’s identity was created.

string

The customer’s email address.

boolean

If true, the customer confirmed their email address.

string

The email address suggested for the customer based on tracked activity, such as a form submission. The customer has not confirmed this address. This field is independent of email and is not used for identity merging or segment membership, including built-in lead segments.

array

An array of custom key-value objects available for the session duration.

Show session_fields properties

string

The value associated with the custom session field key.

string

The customer’s name.

string

The customer’s phone number.

string

The timestamp of the most recent event seen by the customer, in RFC 3339 format. All earlier events are considered seen.

object

Geolocation and page-view data from the customer’s most recent online visit.

Show visit properties

string

The date and time when the visit started.

string

The date and time when the visit ended.

string

The URL that referred the customer to the website.

string

The customer’s IP address.

string

The customer’s browser user-agent string.

object

The customer’s approximate geolocation.

Show visit.geolocation properties

string

The country name.

string

The ISO 3166-1 alpha-2 country code.

string

The region name.

string

The city name.

string

The IANA time zone name.

string

The latitude of the approximate location.

string

The longitude of the approximate location.

array

The pages opened during the visit, ordered from most to least recent.

Show visit.last_pages properties

string

required

The date and time when the page was opened.

string

required

The page URL.

string

The page title.

boolean

If true, the customer is present in the chat.

object

Counters and activity timestamps for the customer.

Show statistics properties

integer

The number of chats started by the customer.

integer

The number of threads started by the customer.

integer

The number of customer visits.

integer

The number of customer page views.

integer

The number of greetings shown to the customer.

integer

The number of greetings accepted by the customer.

integer

The number of greetings that resulted in a conversion.

integer

The number of the customer’s tickets.

integer

The number of the customer’s tickets in the inbox.

integer

The number of the customer’s archived tickets.

integer

The number of the customer’s tickets marked as spam.

integer

The number of the customer’s tickets in the trash.

integer

The number of the customer’s orders.

object

The customer’s identities on supported messaging channels.

Show omnichannel properties

array

The customer’s Facebook Messenger identities.

Show omnichannel.fbmessenger properties

string

required

The Facebook Messenger ID.

string

The Facebook Messenger display name.

string

The customer’s first name.

string

The customer’s last name.

string

The URL of the customer’s profile picture.

string

The customer’s gender.

string

The customer’s locale.

boolean

If true, the customer is a verified Facebook user.

array

The customer’s Twilio identities.

Show omnichannel.twilio properties

string

required

The Twilio phone number.

array

The customer’s WhatsApp identities.

Show omnichannel.whatsapp properties

string

required

The WhatsApp ID.

string

The WhatsApp display name.

string

required

The WhatsApp phone number in E.164 format.

array

The customer’s shopping carts.

Show carts properties

string

required

Unique identifier of the store.

string

required

The store platform, such as shopify.

boolean

required

If true, the customer is signed in to the store.

number

required

The cart subtotal in the original currency.

number

required

The cart total in the original currency.

number

required

The cart subtotal converted to United States dollars.

number

required

The cart total converted to United States dollars.

string

required

The ISO 4217 currency code.

array

required

The items in the cart.

Show carts.items properties

integer

required

The item ID.

integer

required

The quantity of the item in the cart.

integer

required

The product variant ID.

string

required

The date and time when the cart was last updated, in RFC 3339 format.

object

The customer’s address data.

Show address properties

string

The street address.

string

The city name.

string

The country name.

string

The state or region name.

string

The postal code.

object

The customer’s property values, keyed by customer property ID.

Show customer_properties properties

object

The value and update metadata for the customer property.

Show customer_properties.<property_id> properties

any

required

The current property value. Its type is determined by the property definition’s CustomerPropertyType.

string

required

The date and time when the value was last updated, in RFC 3339 format.

string

The account ID of the agent who last set the value.

string

The client ID of the app that last set the value.

string

The customer’s relationship level. Possible values: vip.

array

The customer’s segment memberships.

Show segment_memberships properties

integer

required

The segment definition ID.

boolean

required

If true, the customer meets all conditions of the segment.

string

The date and time when is_member last changed. This field is returned if the customer belonged to the segment at least once.

array

Account IDs of agents credited with the customer joining the segment. This field is returned when an agent’s change added the customer to the segment.

object

An object where the keys are the names of the conditions the customer meets (for example, email_set) and the values are condition provenance objects.

Show segment_memberships.conditions_provenance properties

object

Details about the most recent update to the customer field or property that the condition checks.

Show segment_memberships.conditions_provenance.<condition> properties

string

required

The date and time when the customer field or property evaluated by the condition was last updated, in RFC 3339 format.

string

The account ID of the agent who updated the customer field or property. The field is omitted when the update is not attributed to an agent.

string

The client ID identifies the API client associated with the access token used for the update. Updates made through the Text app also include this value. The field is omitted when no client ID was recorded for the update.

string

The customer’s internal LC2 identifier.

boolean

required

If true, the requester follows the customer.

boolean

required

If true, the customer is online.

array

The IDs of groups associated with the customer.

array

The customer’s tickets.

Show tickets properties

string

required

The ticket ID.

string

required

The date and time when the ticket was created, in RFC 3339 format.

string

The customer’s activity state. This field is omitted when the activity state is unavailable. Possible values: unknown, browsing, queued, invited, chatting, chat closed, offline.

Sample Customer data structure

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "email_verified": false,
  "suggested_email": "t.anderson@example.com",
  "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",
      "latitude": "51.1043015",
      "longitude": "17.0335007"
    },
    "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,
    "page_views_count": 18,
    "greetings_shown_count": 4,
    "greetings_accepted_count": 2,
    "greetings_converted_count": 1,
    "tickets_count": 12,
    "tickets_inbox_count": 3,
    "tickets_archive_count": 7,
    "tickets_spam_count": 1,
    "tickets_trash_count": 1,
    "orders_count": 2
  },
  "__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"
        }
      },
      {
        "phone_number": "+18008529002"
      }
    ],
    "whatsapp": [
      {
        "id": "15550001234",
        "name": "Thomas Anderson",
        "phone_number": "+15550001234"
      }
    ]
  },
  "carts": [
    {
      "store_uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
      "store_platform": "shopify",
      "customer_signed_in": true,
      "subtotal": 100,
      "total": 120,
      "subtotal_usd": 100,
      "total_usd": 120,
      "currency": "USD",
      "items": [
        {
          "id": 123456789,
          "quantity": 2,
          "variant_id": 987654321
        }
      ],
      "last_updated_at": "2026-07-15T09:42:23.048723Z"
    }
  ],
  "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"
    }
  },
  "relationship_level": "vip",
  "segment_memberships": [
    {
      "segment_id": 0,
      "is_member": true,
      "membership_last_updated_at": "2026-07-15T09:31:45.075731Z",
      "membership_attribution": ["464d206a-ba7d-4ce1-98d6-d03f8f14970e"],
      "conditions_provenance": {
        "email_set": {
          "last_updated_at": "2026-07-15T09:31:45.075731Z",
          "agent_account_id": "464d206a-ba7d-4ce1-98d6-d03f8f14970e",
          "agent_client_id": "71d32c598862b01b9e2298281339dbc2"
        },
        "phone_number_set": {
          "last_updated_at": "2026-07-15T09:42:23.048723Z"
        }
      }
    }
  ]
}

Cart

Fields

string

required

Unique identifier of the store.

string

required

The store platform, such as shopify.

boolean

required

If true, the customer is signed in to the store.

number

required

The cart subtotal in the original currency.

number

required

The cart total in the original currency.

number

required

The cart subtotal converted to United States dollars.

number

required

The cart total converted to United States dollars.

string

required

The ISO 4217 currency code.

array

required

The items in the cart.

Show items properties

integer

required

The item ID.

integer

required

The quantity of the item in the cart.

integer

required

The product variant ID.

string

required

The date and time when the cart was last updated, in RFC 3339 format.

Sample Cart data structure

{
  "store_uuid": "70cb9e59-b639-41c5-81cf-71db11972cff",
  "store_platform": "shopify",
  "customer_signed_in": true,
  "subtotal": 100,
  "total": 120,
  "subtotal_usd": 100,
  "total_usd": 120,
  "currency": "USD",
  "items": [
    {
      "id": 123456789,
      "quantity": 2,
      "variant_id": 987654321
    }
  ],
  "last_updated_at": "2026-07-15T09:42:23.048723Z"
}

Cart item

Fields

integer

required

The item ID.

integer

required

The quantity of the item in the cart.

integer

required

The product variant ID.

Sample cart item data structure

{
  "id": 123456789,
  "quantity": 2,
  "variant_id": 987654321
}

Customer property

Customer properties are identified by the UUID generated in the Create customer property definition method. The property’s type is set on creation.

Fields

any

required

The current property value. Its type is determined by the property definition’s CustomerPropertyType.

string

required

The date and time when the value was last updated, in RFC 3339 format.

string

The account ID of the agent who last set the value.

string

The client ID of the app that last set the value.

Sample customer property data structure

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

Segment membership

A segment membership records whether a customer satisfies a segment definition. For more information, see Customer segments.

Sample Segment membership data structure

{
  "segment_id": 0,
  "is_member": true,
  "membership_last_updated_at": "2026-07-15T09:31:45.075731Z",
  "membership_attribution": ["464d206a-ba7d-4ce1-98d6-d03f8f14970e"],
  "conditions_provenance": {
    "email_set": {
      "last_updated_at": "2026-07-15T09:31:45.075731Z",
      "agent_account_id": "464d206a-ba7d-4ce1-98d6-d03f8f14970e",
      "agent_client_id": "71d32c598862b01b9e2298281339dbc2"
    },
    "phone_number_set": {
      "last_updated_at": "2026-07-15T09:42:23.048723Z"
    }
  }
}

Fields

integer

required

The segment definition ID.

boolean

required

If true, the customer meets all conditions of the segment.

string

The date and time when is_member last changed. This field is returned if the customer belonged to the segment at least once.

array

Account IDs of agents credited with the customer joining the segment. This field is returned when an agent’s change added the customer to the segment.

object

An object where the keys are the names of the conditions the customer meets (for example, email_set) and the values are condition provenance objects.

Show conditions_provenance properties

object

Details about the most recent update to the customer field or property that the condition checks.

Show conditions_provenance.<condition> properties

string

required

The date and time when the customer field or property evaluated by the condition was last updated, in RFC 3339 format.

string

The account ID of the agent who updated the customer field or property. The field is omitted when the update is not attributed to an agent.

string

Other common structures

These structures describe shared objects used throughout the Agent Chat API.

Access

Fields

array

The IDs of groups with access. The 0 value grants access to all agents.

Sample Access data structure

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

Chats

Fields

string

required

The chat ID.

object

The chat thread. See Threads.

array

required

The chat users. See Agent and Customer.

object

Custom chat properties organized by namespace and property name.

Show properties properties

object

The custom properties in the namespace.

Show properties.<namespace> properties

any

The custom property value.

object

The groups that can access the chat.

Show access properties

array

The IDs of groups with access. The 0 value grants access to all agents.

boolean

required

If true, the requester follows the chat.

Sample Chat data structure

{
  "id": "PJ0MRSHTDG",
  "thread": {
    "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": ""
          }
        ]
      }
    ],
    "summary": {
      "status": "ok",
      "version": 1,
      "content": {
        "title": "Refund request for order #1042",
        "summary_bullets": [
          "Customer asked about a refund",
          "Agent confirmed the order number",
          "Refund scheduled for next week"
        ]
      },
      "updated_at": "2020-05-12T11:43:02.108000Z"
    },
    "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"
    }
  ],
  "properties": {
    "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. When you have no access to the thread, last_thread_info contains a restricted_access field instead of last_event_per_type.

Fields

string

required

The chat ID.

object

Information about the most recent thread.

Show last_thread_info properties

string

required

The thread ID.

string

required

The thread creation timestamp in RFC 3339 format with microsecond precision.

array

required

The IDs of users participating in the thread.

object

Custom thread properties organized by namespace and property name. See Properties.

boolean

required

If true, the thread is active.

object

The groups that can access the thread. See Access.

object

The thread’s queue information. See Threads.

object

The most recent event of each event type, keyed by event type.

Show last_thread_info.last_event_per_type properties

object

The most recent event of the specified type. See Events.

string

The reason access to the thread is restricted. This field replaces last_thread_info.last_event_per_type when the requester cannot access the thread.

array

required

The chat users. See Agent and Customer.

object

Custom chat properties organized by namespace and property name. See Properties.

object

The groups that can access the chat. See Access.

boolean

required

If true, the requester follows the chat.

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": {
        "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": {
        "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"
    }
  ],
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "is_followed": false
}

Sample restricted 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"
    },
    "restricted_access": "You can't access threads older than 60 days on starter plan"
  },
  "users": [],
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "is_followed": false
}

Form fields

A component of the Form event.

Fields

array

required

The fields in the form.

Show fields properties

string

required

The form field type. Possible values: checkbox, date, email, group_chooser, name, phone, question, radio, select, subject, textarea.

string

required

The form field ID.

string

required

The form field label.

boolean

If true, the customer must complete the field before submitting the form.

string

The ID of the customer property updated when the customer submits the form.

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

Sample Form fields

{
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "required": true,
      "customer_property_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "Support"
        }
      ]
    },
    {
      "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.

Fields

array

required

The completed fields in the form.

Show fields properties

string

required

The form field type. Possible values: checkbox, date, email, group_chooser, name, phone, question, radio, select, subject, textarea.

string

required

The form field ID.

string

required

The form field label.

any

The answer to a single-value field. For choice fields, the value is an object.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID. This field applies to group_chooser fields.

array

The answers to a multi-value field.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

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 stores. You can set them on a chat, thread, or event. For more information, see the Configuration API documentation.

Fields

object

The custom properties in the namespace.

Show properties.<namespace> properties

any

The custom property value.

Sample Properties data structure

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

Threads

Fields

string

required

The thread ID.

object

The groups that can access the thread.

Show access properties

array

The IDs of groups with access. The 0 value grants access to all agents.

boolean

required

If true, the thread is active. If false, the thread is inactive.

array

The IDs of users participating in the thread.

array

The events in the thread. This field is absent when restricted_access is present.

Show events properties

string

required

The event ID.

string

The custom event ID.

string

required

The event type.

string

required

The event creation timestamp in RFC 3339 format with microsecond precision.

string

The ID of the event author.

string

required

The event visibility. Possible values: all, agents.

string

The message text. Present for message events.

object

Custom event properties organized by namespace and property name.

Show events.properties properties

object

The custom event properties in the namespace.

Show events.properties.<namespace> properties

any

The custom event property value.

object

The AI-generated thread summary. This field is present only for inactive threads when the auto_summary_enabled chat property is enabled or when the summary was requested through Request thread summary.

Show summary properties

string

required

The summary generation status. Possible values: ok, error.

integer

The summary format version. Possible values: 1. This field is absent from the legacy format.

object

The structured summary content. This field is present in version 1.

Show summary.content properties

string

required

The short title describing the thread.

array

required

The key points summarizing the thread.

string

The summary with bullet points in a single string. This field is present in the legacy format.

string

required

The date and time when the summary was last updated, in RFC 3339 format with microsecond precision.

object

Custom thread properties organized by namespace and property name.

Show properties properties

object

The custom thread properties in the namespace.

Show properties.<namespace> properties

any

The custom thread property value.

string

The reason access to the thread is restricted.

object

The thread’s queue information. This field is present while the chat is waiting for an available agent.

Show queue properties

integer

required

The chat’s position in the queue.

integer

required

The approximate wait time for an available agent, in seconds.

string

The date and time when the chat entered the queue, in RFC 3339 format.

integer

The total time the chat spent in queues, in seconds.

string

The preceding thread ID.

string

The following thread ID.

string

The preceding thread ID accessible to the requester. This field is returned by list_archives.

string

The following thread ID accessible to the requester. This field is returned by list_archives.

string

required

The server-generated thread creation timestamp in RFC 3339 format with microsecond precision.

array

The thread tags. This field is returned when the thread has at least one tag.

object

The customer’s network, browser, and geolocation data for the thread.

Show customer_visit properties

string

The customer’s IP address.

string

The customer’s browser user-agent string.

object

The customer’s approximate geolocation.

Show customer_visit.geolocation properties

string

The country name.

string

The ISO 3166-1 alpha-2 country code.

string

The region name.

string

The city name.

string

The IANA time zone name.

string

The latitude of the approximate location.

string

The longitude of the approximate location.

Sample Thread data structure

{
  "id": "K600PKZON8",
  "active": true,
  "user_ids": ["smith@example.com"],
  "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",
      "properties": {
        "property_namespace": {
          "property_name": "property_value"
        }
      }
    },
    {
      "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"
    }
  ],
  "summary": {
    "status": "ok",
    "version": 1,
    "content": {
      "title": "Refund request for order #1042",
      "summary_bullets": [
        "Customer asked about a refund",
        "Agent confirmed the order number",
        "Refund scheduled for next week"
      ]
    },
    "updated_at": "2020-05-07T07:12:03.512000Z"
  },
  "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",
  "previous_accessible_thread_id": "K600PKZOL8",
  "next_accessible_thread_id": "K600PKZOP8",
  "customer_visit": {
    "ip": "<customer_ip>",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36",
    "geolocation": {
      "country": "Poland",
      "country_code": "PL",
      "region": "Dolnoslaskie",
      "city": "Wroclaw",
      "timezone": "Europe/Warsaw",
      "latitude": "51.1043015",
      "longitude": "17.0335007"
    }
  },
  "created_at": "2020-05-07T07:11:28.288340Z"
}

Sample restricted Thread data structure

{
  "id": "K600PKZON8",
  "active": false,
  "user_ids": ["smith@example.com"],
  "restricted_access": "You can't access threads older than 60 days on starter plan",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [1, 2]
  },
  "created_at": "2020-05-07T07:11:28.288340Z"
}

Sample Thread with legacy summary

{
  "id": "K600PKZON8",
  "active": false,
  "user_ids": ["smith@example.com"],
  "events": [],
  "summary": {
    "status": "ok",
    "text": "• Customer asked about a refund\n• Agent confirmed the order number\n• Refund scheduled for next week",
    "updated_at": "2020-05-07T07:12:03.512000Z"
  },
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [1, 2]
  },
  "created_at": "2020-05-07T07:11:28.288340Z"
}

Thread summary

Text generates thread summaries with "version": 1. A stored summary without version uses the legacy format.

Version 1
Version 0 (legacy)

Fields

string

required

The summary generation status. Possible values: ok, error.

integer

required

The summary format version. Must be 1.

object

required

The structured summary content.

Show content properties

string

required

The short title describing the thread.

array

required

The key points summarizing the thread.

string

required

The date and time when the summary was last updated, in RFC 3339 format with microsecond precision.

Sample thread summary data structure

{
  "status": "ok",
  "version": 1,
  "content": {
    "title": "Refund request for order #1042",
    "summary_bullets": [
      "Customer asked about a refund",
      "Agent confirmed the order number",
      "Refund scheduled for next week"
    ]
  },
  "updated_at": "2026-07-21T10:12:00.000000Z"
}

Fields

string

required

The summary generation status. Possible values: ok, error.

string

required

The summary with bullet points in a single string.

string

required

The date and time when the summary was last updated, in RFC 3339 format with microsecond precision.

Sample thread summary data structure

{
  "status": "ok",
  "text": "• Customer asked about a refund\n• Agent confirmed the order number\n• Refund scheduled for next week",
  "updated_at": "2026-07-21T10:12:00.000000Z"
}

Deleted event

The Deleted Event is returned to agents with the normal role in place of the original event.

Fields

string

required

The event ID.

string

required

The event creation timestamp in RFC 3339 format with microsecond precision.

string

required

The original event type.

string

required

The event visibility. Possible values: all, agents.

boolean

required

If true, the event is deleted.

string

The ID of the event author.

string

The custom event ID.

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

Overview

Methods

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Agent

My profile

Customer

Cart

Cart item

Customer property

Segment membership

Other common structures

Access

Chats

Chat info

Form fields

Filled form fields

Properties

Threads

Thread summary

Deleted event

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​System

​Users

​Agent

​My profile

​Customer

​Cart

​Cart item

​Customer property

​Segment membership

​Other common structures

​Access

​Chats

​Chat info

​Form fields

​Filled form fields

​Properties

​Threads

​Thread summary

​Deleted event

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Agent

My profile

Customer

Cart

Cart item

Customer property

Segment membership

Other common structures

Access

Chats

Chat info

Form fields

Filled form fields

Properties

Threads

Thread summary

Deleted event