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, email, group_chooser, name, 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, email, group_chooser, name, 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, email, group_chooser, name, 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, email, group_chooser, name, 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.

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

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

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"
  },
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  }
}

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.

object

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

string

required

The template that determines how the rich message is displayed.

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

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",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "template_id": "cards",
  "elements": [
    {
      "title": "Lorem ipsum dolor.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "image": {
        "name": "image25.png",
        "url": "https://example.com/image25.png",
        "content_type": "image/png",
        "size": 123444,
        "width": 640,
        "height": 480,
        "alternative_text": "A picture of lorem ipsum"
      },
      "buttons": [
        {
          "text": "yes",
          "postback_id": "action_yes",
          "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
        },
        {
          "text": "no",
          "postback_id": "action_no",
          "user_ids": []
        },
        {
          "type": "phone",
          "text": "value",
          "value": "790034890",
          "webview_height": "tall",
          "postback_id": "action_call",
          "user_ids": [],
          "target": "current"
        }
      ]
    }
  ]
}

Custom

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

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 customer name.

array

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

Show session_fields properties

string

A custom session field value.

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,
  "avatar": "https://example.com/avatar.png",
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ],
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}

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 summaries

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

string

required

The chat ID.

string

The ID of the most recent thread.

string

The creation timestamp of the most recent thread, in RFC 3339 format with microsecond precision.

array

The chat users. See Customer and Agent.

object

required

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

Show last_event_per_type properties

object

The most recent event of the specified type.

Show last_event_per_type.<event_type> properties

string

required

The ID of the thread containing the event.

integer

The thread order within the chat.

string

required

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

object

required

The event data. See Events.

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 summary data structure

{
  "id": "PJ0MRSHTDG",
  "last_thread_id": "QA1B38GHGI",
  "last_thread_created_at": "2020-05-08T08:22:21.128420Z",
  "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"
    }
  ],
  "last_event_per_type": {
    "message": {
      "thread_id": "QA1B38GHGI",
      "thread_order": 1,
      "thread_created_at": "2020-05-14T07:22:30.779000Z",
      "event": {
        "id": "QA1B38GHGI_1",
        "created_at": "2020-05-14T07:22:40.269000Z",
        "type": "message",
        "properties": {
          "property_namespace": {
            "property_name": "property_value"
          }
        },
        "text": "Hello",
        "author_id": "bbb67d600796e9f277e360e842418833",
        "custom_id": "1589440960204.71699349177"
      }
    },
    "system_message": {
      "thread_id": "QA1B38GHGI",
      "thread_order": 1,
      "thread_created_at": "2020-05-14T07:22:30.779000Z",
      "event": {
        "id": "QA1B38GHGI_3",
        "created_at": "2020-05-14T08:18:44.015000Z",
        "type": "system_message",
        "text": "The chat was closed because Agent Smith had lost internet connection",
        "system_message_type": "routing.archived_disconnected",
        "text_vars": {
          "agent": "Agent Smith"
        }
      }
    }
  },
  "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, 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, email, group_chooser, name, 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, email, group_chooser, name, 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

Users

Customer

Agent

Other common structures

Access

Chats

Chat summaries

Forms

Form fields

Filled form fields

Properties

Threads

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​Users

​Customer

​Agent

​Other common structures

​Access

​Chats

​Chat summaries

​Forms

​Form fields

​Filled form fields

​Properties

​Threads

Events

File

Form

Filled form

Message

Rich message

Custom

System message

Users

Customer

Agent

Other common structures

Access

Chats

Chat summaries

Forms

Form fields

Filled form fields

Properties

Threads