Data structures

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

Events

Events are sent to a chat through the send_event method.

File

The File event represents an uploaded file.

Request

string

The custom event ID.

string

required

The event type. Must be file.

object

Custom 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 the image.

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.

object

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

Sample File in response

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

Form

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

Request

string

The custom event ID.

string

required

The event type. Must be form.

object

Custom 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

Whether an answer to the field is required.

array

The selectable options for checkbox, group_chooser, radio, and select fields.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

integer

The group ID for a group_chooser option.

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

The ID of the event author. Omitted when the form is generated by the system.

object

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

Whether an answer to the field is required.

array

The selectable options for checkbox, group_chooser, radio, and select fields.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

integer

The group ID for a group_chooser option.

Sample Form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "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"
        }
      ]
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department",
      "required": true,
      "options": [
        {
          "id": "2",
          "group_id": 1,
          "label": "Marketing"
        }
      ]
    }
  ]
}

Filled form

The Filled form event contains data submitted through a prechat or postchat form.

Request

string

The custom event ID.

string

required

The event type. Must be filled_form.

string

default:"all"

required

The event recipients. Possible values: all, agents.

object

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

string

required

The form ID.

array

required

The fields in the form. 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 answer to the form field.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID for a group_chooser field.

array

The selected answers for a field that accepts multiple values.

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.

object

Custom 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 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 answer to the form field.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID for a group_chooser field.

array

The selected answers for a field that accepts multiple values.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

Sample Filled form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "filled_form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "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 sent to chat users.

Request

string

The custom event ID.

string

required

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

string

required

The event type. Must be message.

object

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

object

The postback that generated the message from a rich message event.

Show postback properties

string

required

The ID of the postback 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. Use it together with postback.value; if either field is present, the other is required.

string

The postback value. Use it together with postback.type; if either field is present, the other is required.

object

The ecommerce data from the rich message.

Show postback.ecommerce properties

string

required

The ID of the product displayed in the rich message.

string

The ID of the selected product option.

number

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.

string

required

The ID of the event author.

string

required

The message text.

object

The postback that generated the message from a rich message event.

Show postback properties

string

required

The ID of the postback 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. Use it together with postback.value; if either field is present, the other is required.

string

The postback value. Use it together with postback.type; if either field is present, the other is required.

object

The ecommerce data from the rich message.

Show postback.ecommerce properties

string

The ID of the product displayed in the rich message.

string

The ID of the selected product option.

number

The product quantity.

object

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

boolean

Whether 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",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890",
    "ecommerce": {
      "product_id": "prod123",
      "option_id": "opt1",
      "quantity": 1
    }
  },
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "deleted": false
}

Rich message

The Rich message event contains interactive rich message content.

Request

string

The custom event ID.

string

required

The event type. Must be rich_message.

object

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

array

An array of up to 10 rich message elements.

Show elements properties

string

required

The formatted title of the rich message element.

string

required

The formatted subtitle of the rich message element.

object

required

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 file size in bytes.

integer

The image width in pixels.

integer

The image height in pixels.

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 provided, elements.buttons.value is also required. Possible values: webview, message, url, phone.

string

The button value. If provided, elements.buttons.type is also required. For a webview button, it can provide a custom Moment title.

string

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

string

required

The action identifier sent through send_rich_message_postback.

array

required

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

string

The browsing context for a url button. Possible values: new, current.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event type.

string

required

The ID of the event author.

string

required

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

string

required

The event visibility.

object

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

string

required

The template that determines how the rich message is displayed.

array

required

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 file size in bytes.

integer

The image width in pixels.

integer

The image height in pixels.

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 button behavior. 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 elements.buttons.type is webview. Possible values: compact, full, tall.

string

required

The action identifier sent through send_rich_message_postback.

array

required

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

string

The browsing context for a url button. Possible values: new, current.

object

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

Show elements.ecommerce properties

string

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

string

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

Whether the product option is available.

boolean

Whether 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

The Custom event contains a customizable payload.

Request

string

The custom event ID.

string

required

The event type. Must be custom.

object

The custom JSON content.

object

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

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event type.

string

required

The ID of the event author.

string

required

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

object

The custom JSON content.

object

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

Sample Custom event in response

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

System message

The System message event is generated by the system in specific situations.

Request

string

The custom event ID.

string

required

The event type. Must be system_message.

string

The message text.

string

required

The system message type. See System message types.

object

The variables substituted into the system message text.

Response

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 message text.

string

required

The system message type. See System message types.

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",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "system_message",
  "text": "hello there",
  "system_message_type": "routing.assigned",
  "text_vars": {
    "agent": "John Doe"
  }
}

System

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

Response

string

required

The event ID.

string

The custom event ID.

string

required

The system that generated the event. See System event sources.

string

required

The event type. Always system.

string

required

The system event subtype. See System event subtypes.

integer

required

The system event schema version.

string

required

The JSON-encoded event details.

string

required

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

Sample System event in response

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

Users

Users represent customers and agents participating in chats.

Customer

string

required

The customer ID.

string

required

The user type. Always customer.

string

The customer avatar URL.

string

The customer email address.

boolean

Whether the customer confirmed their email address.

string

The email address suggested from tracked customer activity, such as a form submission. The customer has not confirmed this address. It is independent of email and isn’t used for identity merging or segment membership, including built-in lead segments.

string

The customer name.

string

The customer phone number.

array

Custom key-value pairs available for the duration of the customer session.

Show session_fields properties

string

A custom session field value.

object

The customer’s omnichannel data.

Show omnichannel properties

array

The customer’s Facebook Messenger profiles.

Show omnichannel.fbmessenger properties

string

required

The Facebook Messenger profile ID.

string

The profile name.

string

The profile first name.

string

The profile last name.

string

The profile picture URL.

string

The profile gender.

string

The profile locale.

boolean

Whether Facebook verified the user.

array

The customer’s Twilio profiles.

Show omnichannel.twilio properties

object

A Twilio profile keyed by phone number.

Show omnichannel.twilio.<phone_number> properties

string

required

The profile phone number.

array

The customer’s WhatsApp profiles.

Show omnichannel.whatsapp properties

string

required

The WhatsApp profile ID.

string

The profile name.

string

required

The profile phone number.

object

The customer’s address data.

Show address properties

string

The street address.

string

The city.

string

The country.

string

The state or region.

string

The postal code.

boolean

If true, the customer is present in the chat.

string

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

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/avatar.png",
  "phone_number": "+18008529001",
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ],
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "omnichannel": {
    "fbmessenger": [
      {
        "id": "fb_messenger_id",
        "name": "Thomas Anderson",
        "first_name": "Thomas",
        "last_name": "Anderson",
        "profile_pic": "https://example.com/avatars/1.png",
        "gender": "male",
        "locale": "en_US",
        "is_verified_user": true
      }
    ],
    "twilio": [
      {
        "+18008529001": {
          "phone_number": "+18008529001"
        }
      }
    ],
    "whatsapp": [
      {
        "id": "15550001234",
        "name": "Thomas Anderson",
        "phone_number": "+15550001234"
      }
    ]
  },
  "address": {
    "address": "1600 Pennsylvania Avenue NW",
    "city": "Washington",
    "country": "United States",
    "state": "DC",
    "postal_code": "20500"
  }
}

Agent

string

required

The agent ID.

string

required

The user type. Always agent.

string

The agent’s name.

string

required

The URL of the agent’s avatar.

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

The agent’s job title.

Sample Agent data structure

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

Other common structures

These structures support chats, forms, properties, and threads.

Access

array

The IDs of groups that can access the resource. Group 0 grants access to all agents.

Sample Access data structure

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

Chats

string

required

The chat ID.

object

The chat thread. See Threads.

array

The chat users. See Customer and Agent.

object

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

Show properties properties

object

A property namespace.

Show properties.<namespace> properties

any

A property value.

object

The chat access settings.

Show access properties

array

The IDs of groups that can access the chat. Group 0 grants access to all agents.

Sample Chat data structure

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

Chat info

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

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.

object

required

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.

array

The chat users. See Customer and Agent.

object

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

object

The chat access settings. See Access.

boolean

required

If true, the chat’s most recent thread is active.

Sample Chat info data structure

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

Forms

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

string

The form ID.

array

required

The fields in the form. See Form fields.

Show fields properties

string

required

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

string

Field ID, for all field types.

string

required

The field label.

boolean

Whether an answer to the field is required.

array

For checkbox, group_chooser, radio and select.

Show fields.options properties

string

required

An identifier of each option a customer can choose.

string

required

The field label.

integer

The group ID for a group_chooser option.

Sample Form data structure

{
  "id": "157986144052005549",
  "fields": [
    {
      "id": "157986144052003238",
      "type": "header",
      "label": "Welcome to our chat! Please fill in the form below before starting the chat."
    },
    {
      "id": "157986144052008371",
      "type": "name",
      "label": "Name:",
      "required": false
    },
    {
      "id": "157986144052005782",
      "type": "email",
      "label": "E-mail:",
      "required": false
    },
    {
      "id": "157986144052009331",
      "type": "group_chooser",
      "label": "Choose a department:",
      "required": true,
      "options": [
        {
          "id": "0",
          "group_id": 1,
          "label": "Marketing"
        },
        {
          "id": "1",
          "group_id": 2,
          "label": "Sales"
        },
        {
          "id": "2",
          "group_id": 0,
          "label": "General"
        }
      ]
    }
  ]
}

Form fields

A component of the Form event.

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.

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.

array

required

The fields in the submitted 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 submitted answer.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

The selected group ID for a group_chooser field.

array

The submitted answers for a field that accepts multiple values.

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 pairs that can be set on a chat, thread, or event. For details, see the Configuration API.

Sample Properties data structure

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

Threads

string

required

The thread ID.

object

The thread access settings.

Show access properties

array

The IDs of groups that can access the thread. Group 0 grants access to all agents.

boolean

required

Whether the thread is active.

array

required

The IDs of users participating in the thread.

array

The events in the thread.

Show events properties

string

required

The event ID.

string

required

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

string

required

The event type.

object

The event properties.

string

The event text.

string

required

The system message type. Present for system message events.

object

The variables substituted into the system message text.

string

The ID of the event author.

string

The custom event ID.

object

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

Show properties properties

object

A property namespace.

Show properties.<namespace> properties

any

A property value.

object

The queue information. Present only when the chat is queued.

Show queue properties

integer

required

The chat position in the queue.

integer

required

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

string

required

The timestamp when the chat entered the queue.

string

The ID of the preceding thread.

string

The ID of the following thread.

string

required

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

Sample Thread data structure

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

Overview

Chats

Configuration

Events

Localization

Properties

Customers

Status

Other

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Customer

Agent

Other common structures

Access

Chats

Chat info

Forms

Form fields

Filled form fields

Properties

Threads

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​System

​Users

​Customer

​Agent

​Other common structures

​Access

​Chats

​Chat info

​Forms

​Form fields

​Filled form fields

​Properties

​Threads

Events

File

Form

Filled form

Message

Rich message

Custom

System message

System

Users

Customer

Agent

Other common structures

Access

Chats

Chat info

Forms

Form fields

Filled form fields

Properties

Threads