Data structures

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

Events

One of the data structures are events. They are sent to a chat via the send_event method. Apart from events, there are also Properties, Users, and Other common data structures. These are the available event types:

File
Form
Filled form
Message
Rich message
Custom
System message

File

The File event indicates about an uploaded file. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the Text CDN. It’s recommended to use the URL returned by `upload_file`.
`alternative_text`	no	`string`	Only applicable to images

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`visibility`	always
`properties`	optionally
`name`	always
`url`	always
`thumbnail_url`, `thumbnail2x_url`	only for images
`content_type`	always
`size`, `width`, `height`	only for images
`alternative_text`	only for images

Sample File in response

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

Form

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

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`form`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`visibility`	always
`properties`	optionally
`form_id`	always
`form_type`	optionally	The most popular form types include: `prechat`, `postchat`, `ask_for_email`, but those aren’t the only possible options. If you don’t see this field in a chat, it means that chat had been started before we introduced this field (see Changelog).
`fields`	always	An array of form fields

A sample use case: sending a form in the chat after a pre-determined agent’s inactivity period. This could be a way of gathering contact info from customers so that the overloaded agent can contact them later.

Sample Form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "type": "form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visibility": "all",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "form_type": "prechat",
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "required": true
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "required": false
    },
    {
      "type": "question",
      "id": "154417206262601585",
      "label": "What are you looking for?",
      "required": false
    },
    {
      "type": "textarea",
      "id": "154417206262601586",
      "label": "Additional info",
      "required": false
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "Support"
        }
      ]
    },
    {
      "type": "select",
      "id": "154417206262602572",
      "label": "Country",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "USA"
        },
        {
          "id": "1",
          "label": "UK"
        }
      ]
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "required": false,
      "options": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    }
  ]
}

Filled form

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

Field	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`filled_form`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`form_id`	yes	`string`
`fields`	yes	`array`	The fields a form contains. See filled form fields for details.

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always
`author_id`	always
`visibility`	always
`properties`	optionally
`form_id`	always
`form_type`	optionally	The most popular form types include: `prechat`, `postchat`, `ask_for_email`, but those aren’t the only possible options. If you don’t see this field in a chat, it means that chat had been started before we introduced this field (see Changelog).
`fields`	always	The fields a form contains. See filled form fields for details.

Sample Filled form in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "filled_form",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "visibility": "all",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "form_id": "1473433500211",
  "form_type": "prechat",
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "answer": "Thomas Anderson"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "answer": "t.anderson@example.com"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "answer": {
        "id": "0",
        "label": "Support"
      }
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "answers": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department",
      "answer": {
        "id": "2",
        "group_id": 1,
        "label": "Marketing"
      }
    }
  ]
}

Message

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`text`	yes	`string`	Max. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
`type`	yes	`string`	`message`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	Properties
`postback`	no	`object`	Indicates that the message event was generated in response to a rich message event.
`postback.id`	yes	`string`	ID of the postback from the rich message event.
`postback.thread_id`	yes	`string`	ID of the thread with the rich message event.
`postback.event_id`	yes	`string`	ID of the rich message event.
`postback.type`	no	`string`	Should be used together with `postback.value` (when one of them is present, the other is required).
`postback.value`	no	`string`	Should be used together with `postback.type` (when one of them is present, the other is required).

Response

Field	Returned	Notes
`id`	always
`custom_id`	optionally
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`.
`type`	always	`message`
`author_id`	always
`visibility`	always
`text`	always
`postback`	optionally	Appears in a message only when triggered by a rich message.
`postback.id`	always
`postback.thread_id`	always
`postback.event_id`	always
`postback.type`	optionally	Appears only if `postback.value` is present.
`postback.value`	optionally	Appears only if `postback.type` is present.
`properties`	optionally	Properties

Sample Message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "visibility": "all",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  }
}

Rich message

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give your RM a custom ID.
`type`	yes	`string`	Event type: `rich_message`
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	The properties data structure
`template_id`	yes	`string`	Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`.
`elements`	no	`array`	Can contain up to 10 `element` objects.
`elements.title`	yes	`string`	Displays formatted text on RMs.
`elements.subtitle`	yes	`string`	Displays formatted text on RMs.
`elements.image`	yes	`image`	Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `alternative_text`.
`elements.buttons`	no	`array`	Displays buttons. Can contain up to 13 `button` objects.
`elements.buttons.text`	yes	`string`	Text displayed on a button.
`elements.buttons.type`	yes	`string`	Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`.
`elements.buttons.value`	yes	`string`	Should be used together with `elements.buttons.type`. You can use this field to give the rich message of a `webview` type (a Moment) a custom title.
`elements.buttons.webview_height`	yes	`string`	Required only for the `webview` button `type`. Possible values: `compact`, `full`, `tall`.
`elements.buttons.postback_id`	yes	`string`	A description of the sent action. Describes the action sent via `send_rich_message_postback`.
`elements.buttons.user_ids`	yes	`array`	Describes users that sent the postback with `"toggled": true`.
`elements.buttons.target`	no	`string`	Should be used for the `url` button `type`. Specifies if the URL should open in the current or a new tab. Possible values: `new`, `current`.

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.
`visibility`	always
`properties`	optionally
`template_id`	always
`elements`	optionally
`elements.title`	always
`elements.subtitle`	always
`elements.image`	always
`elements.buttons`	optionally
`elements.buttons.text`	always
`elements.buttons.type`	always
`elements.buttons.value`	always
`elements.buttons.webview_height`	always	Unless button `type` is different than `webview`.
`elements.buttons.postback_id`	always
`elements.buttons.user_ids`	always
`elements.buttons.target`	optionally

Sample Rich message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "rich_message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "visibility": "all",
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "template_id": "cards",
  "elements": [
    {
      "title": "Lorem ipsum dolor.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "image": {
        "name": "image25.png",
        "url": "https://example.com/image25.png",
        "content_type": "image/png",
        "size": 123444,
        "width": 640,
        "height": 480,
        "alternative_text": "A picture of lorem ipsum"
      },
      "buttons": [
        {
          "text": "yes",
          "postback_id": "action_yes",
          "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
        },
        {
          "text": "no",
          "postback_id": "action_no",
          "user_ids": []
        },
        {
          "type": "phone",
          "text": "value",
          "value": "790034890",
          "webview_height": "tall",
          "postback_id": "action_call",
          "user_ids": [],
          "target": "current"
        }
      ]
    }
  ]
}

Custom

Custom event is an event with customizable payload. Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the event a custom ID.
`type`	yes	`string`	Event type: `custom`
`content`	no	`object`	The content you define
`visibility`	no	`string`	Possible values: `all` (default), `agents`
`properties`	no	`object`	The properties data structure

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`author_id`	always	Generated server-side
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`content`	optionally
`visibility`	always
`properties`	optionally

Sample Custom event in response

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

System message

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

Parameter	Required	Data type	Notes
`custom_id`	no	`string`	You can give the system message a custom ID.
`type`	yes	`string`	`system_message`
`text`	no	`string`	Text displayed to recipients
`system_message_type`	yes	`string`	System message type
`visibility`	no	`string`	It can be specified when sending system messages via the Send Event method. Possible values: `all`, `agents`.
`text_vars`	no	`object`	Variables used in the text

Response

Field	Returned	Notes
`id`	always	Generated server-side
`custom_id`	optionally
`type`	always
`created_at`	always	Date & time format with a resolution of microseconds, `UTC string`; generated server-side
`text`	optionally
`system_message_type`	always
`visibility`	always

Sample System message in response

{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
  "custom_id": "31-0C-1C-07-DB-16",
  "type": "system_message",
  "created_at": "2017-10-12T15:19:21.010200Z",
  "visibility": "all",
  "text": "Hello there!",
  "system_message_type": "routing.assigned",
  "text_vars": {
    "agent": "John Doe"
  }
}

Users

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

Agent
- My profile
Customer

Agent

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

Sample agent data structure

{
  "id": "smith@example.com",
  "type": "agent",
  "name": "Agent Smith",
  "email": "smith@example.com",
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "visibility": "all"
}

My profile

Field	Req./Opt.	Notes
`routing_status`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string; the timestamp of the most recent event seen by the agent—all the previous events are considered seen.

Sample My profile data structure

{
  "id": "smith@example.com",
  "type": "agent",
  "name": "Agent Smith",
  "email": "smith@example.com",
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "routing_status": "accepting_chats",
  "permission": "administrator"
}

Customer

Field	Req./Opt.	Notes
`agent_last_event_created_at`	optional
`avatar`	optional
`customer_last_event_created_at`	optional
`created_at`	optional
`email`	optional
`email_verified`	optional	Specifies if the customer confirmed their email address. See Request Email Verification.
`session_fields`	optional	An array of custom object-enclosed key-value pairs. Expires along with the session.
`name`	optional
`events_seen_up_to`	optional	RFC 3339 datetime string
`last_visit`	optional
`present`	optional
`statistics`	optional

Sample Customer data structure

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "email_verified": false,
  "avatar": "https://example.com/avatars/1.png",
  "last_visit": {
    "started_at": "2017-10-12T15:19:21.010200Z",
    "ended_at": "2017-10-12T15:21:01.000000Z",
    "referrer": "http://www.google.com/",
    "ip": "<customer_ip>",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
    "geolocation": {
      "country": "Poland",
      "country_code": "PL",
      "region": "Dolnoslaskie",
      "city": "Wroclaw",
      "timezone": "Europe/Warsaw"
    },
    "last_pages": [
      {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.text.com/",
        "title": "Text - Homepage"
      },
      {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.text.com/features/ai-agent/",
        "title": "Text - AI Agents"
      }
    ]
  },
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ],
  "statistics": {
    "chats_count": 3,
    "threads_count": 9,
    "visits_count": 5
  },
  "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"
}

Other common structures

Apart from Events and Users, there are also other common data structures you might work with. Those are:

Access
Chats
Chat summaries
Form fields
Filled form fields
Properties
Threads

Access

Field	Req./Opt.	Note
`group_ids`	required	`group 0` means that all agents can see it.

Sample Access data structure

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

Chats

Field	Req./Opt.
`properties`	optional
`access`	optional

Sample Chat data structure

{
  "id": "PJ0MRSHTDG",
  "threads": [
    {
      "id": "QA37PVJ75B",
      "created_at": "2020-05-12T11:42:47.383000Z",
      "active": false,
      "user_ids": ["smith@example.com", "b7eff798-f8df-4364-8059-649c35c9ed0c"],
      "events": [
        {
          "id": "QA37PVJ75B_1",
          "created_at": "2020-05-12T11:42:47.383001Z",
          "visibility": "all",
          "type": "filled_form",
          "properties": {
            "property_namespace": {
              "property_name": "property_value"
            }
          },
          "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
          "custom_id": "gh4ocmtv83w",
          "form_id": "1002",
          "fields": [
            {
              "id": "10021",
              "type": "name",
              "label": "Name and Surname:",
              "answer": "Thomas Anderson"
            },
            {
              "id": "10022",
              "type": "email",
              "label": "E-mail:",
              "answer": ""
            }
          ]
        }
      ],
      "properties": {
        "property_namespace": {
          "property_name": "property_value"
        }
      },
      "access": {
        "group_ids": [0]
      },
      "tags": ["support", "positive feedback"],
      "previous_thread_id": "QA078URPJL"
    }
  ],
  "users": [
    {
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "name": "Thomas Anderson",
      "events_seen_up_to": "2020-05-12T12:31:46.463000Z",
      "type": "customer",
      "present": true,
      "created_at": "2019-11-02T19:19:50.625101Z",
      "last_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
      },
      "agent_last_event_created_at": "2020-05-12T11:42:47.393002Z",
      "customer_last_event_created_at": "2020-05-12T12:31:46.463000Z"
    },
    {
      "id": "smith@example.com",
      "name": "Agent Smith",
      "email": "smith@example.com",
      "events_seen_up_to": "2020-05-12T12:31:46.999999Z",
      "type": "agent",
      "present": false,
      "avatar": "https://cdn.livechat-files.com/api/file/avatar.png",
      "visibility": "all"
    }
  ],
  "properites": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [1, 2]
  },
  "is_followed": true
}

Chat summaries

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

Sample Chat summary data structure

{
  "id": "PJ0MRSHTDG",
  "last_thread_summary": {
    "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"
    }
  },
  "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",
      "last_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
      },
      "agent_last_event_created_at": "2020-05-12T11:42:47.393002Z",
      "customer_last_event_created_at": "2020-05-12T12:31:46.463000Z"
    },
    {
      "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"
    }
  ],
  "last_event_per_type": {
    "message": {
      "thread_id": "QA37PVJ75B",
      "thread_created_at": "2020-05-12T11:42:47.383000Z",
      "event": {
        "id": "QA37PVJ75B_1",
        "created_at": "2020-05-12T11:42:47.383000Z",
        "type": "message",
        "properties": {
          "property_namespace": {
            "property_name": "property_value"
          }
        },
        "text": "Hello",
        "author_id": "smith@example.com",
        "custom_id": "1589440960204.71699349177"
      }
    },
    "system_message": {
      "thread_id": "QA37PVJ75B",
      "thread_created_at": "2020-05-12T11:42:47.383000Z",
      "event": {
        "id": "QA37PVJ75B_3",
        "created_at": "2020-05-12T12:31:46.563000Z",
        "type": "system_message",
        "text": "The chat was closed because Agent Smith had lost internet connection",
        "system_message_type": "routing.archived_disconnected",
        "text_vars": {
          "agent": "Agent Smith"
        }
      }
    }
  },
  "properites": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "is_followed": false
}

Form fields

A component of the Form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types

Sample Form fields

{
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose"
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry"
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department"
    }
  ]
}

Filled form fields

A component of the Filled form event.

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `subject`, `textarea`, `group_chooser`, `radio`, `select`
`id`	yes	`string`	Field id, for all field types
`label`	yes	`string`	Field label; for all field types
`answer`	yes	`any`	For all field types
`answer.id`	yes	`string`	An identifier of each option a customer can choose. For all field types.
`answer.label`	yes	`string`	Answer label; for all field types
`answer.group_id`	yes	`number`	For `group_chooser`

Sample Filled form fields

{
  "fields": [
    {
      "type": "name",
      "id": "154417206262603539",
      "label": "Your name",
      "answer": "Thomas Anderson"
    },
    {
      "type": "email",
      "id": "154417206262601584",
      "label": "Your email",
      "answer": "t.anderson@example.com"
    },
    {
      "type": "radio",
      "id": "154417206262602571",
      "label": "Chat purpose",
      "answer": {
        "id": "0",
        "label": "Support"
      }
    },
    {
      "type": "checkbox",
      "id": "154417206262604640",
      "label": "Company industry",
      "answers": [
        {
          "id": "0",
          "label": "automotive"
        },
        {
          "id": "1",
          "label": "it"
        }
      ]
    },
    {
      "type": "group_chooser",
      "id": "154417206262605324",
      "label": "Choose department",
      "answer": {
        "id": 2,
        "group_id": 1,
        "label": "Marketing"
      }
    }
  ]
}

Properties

Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.

Sample Properties data structure

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

Threads

Field	Req./Opt.	Note
`access`	optional
`active`	required	Possible values: `true` (thread is still active) or `false`(thread no longer active)
`events`	optional	Doesn’t exists if `restricted_access` is present.
`properties`	optional
`restricted_access`	optional	Contains the reason for access restriction.
`queue`	optional	Present only if the chat is in the queue. The wait time for an available agent is approximated in seconds.
`previous_thread_id`	optional	Present only if there is a preceding thread.
`next_thread_id`	optional	Present only if there is a following thread.
`previous_accessible_thread_id`	optional	Present only if there is a preceding thread accessible for the requester. Field present only in `list_archives`.
`next_accessible_thread_id`	optional	Present only if there is a following thread accessible for the requester. Field present only in `list_archives`.
`created_at`	required	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.
`tags`	optional	An array of tags. Returned only if a thread was tagged.

Sample Thread data structure

{
  "id": "K600PKZON8",
  "active": true,
  "user_ids": ["smith@example.com"],
  "restricted_access": "You can't access threads older than 60 days on starter plan",
  "events": [
    {
      "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
      "custom_id": "31-0C-1C-07-DB-16",
      "type": "message",
      "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "created_at": "2017-10-12T15:19:21.010200Z",
      "text": "Hello there",
      "visibility": "all"
    },
    {
      "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
      "custom_id": "31-0C-1C-07-DB-16",
      "type": "message",
      "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "created_at": "2017-10-12T15:19:21.010200Z",
      "text": "Thank you",
      "visibility": "all"
    }
  ],
  "properties": {
    "property_namespace": {
      "property_name": "property_value"
    }
  },
  "access": {
    "group_ids": [1, 2]
  },
  "tags": ["sales"],
  "queue": {
    "position": 42,
    "wait_time": 1337,
    "queued_at": "2020-05-07T07:11:28.288340Z"
  },
  "queues_duration": 1337,
  "previous_thread_id": "K600PKZOM8",
  "next_thread_id": "K600PKZOO8",
  "created_at": "2020-05-07T07:11:28.288340Z"
}

Overview

Methods

Events

File

Form

Filled form

Message

Rich message

Custom

System message

Users

Agent

My profile

Customer

Other common structures

Access

Chats

Chat summaries

Form fields

Filled form fields

Properties

Threads

​Events

​File

​Form

​Filled form

​Message

​Rich message

​Custom

​System message

​Users

​Agent

​My profile

​Customer

​Other common structures

​Access

​Chats

​Chat summaries

​Form fields

​Filled form fields

​Properties

​Threads

Events

File

Form

Filled form

Message

Rich message

Custom

System message

Users

Agent

My profile

Customer

Other common structures

Access

Chats

Chat summaries

Form fields

Filled form fields

Properties

Threads