Data structures

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

Events

Events are sent to a chat through the send_event method.

File

The File event indicates about an uploaded file.

Request

string

The custom event ID.

string

required

The event type. Must be file.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

string

required

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

string

The alternative text for an image.

Response

string

required

The event ID.

string

The custom event ID.

string

required

The event creation timestamp in UTC with microsecond precision.

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

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

string

required

The file name.

string

required

The file URL.

string

images only

The image thumbnail URLs.

string

required

The file media type.

integer

images only

The file size and image dimensions.

string

images only

The alternative text for the image.

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

string

The custom event ID.

string

required

The event type. Must be form.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

string

required

The form ID.

array

required

The fields in the form. See Form fields.

Show fields properties

string

required

The form field type. Possible values: checkbox, 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

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

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

Response

string

required

The event ID.

string

The custom event ID.

string

required

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

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

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

string

required

The form ID.

string

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

array

required

The fields in the form. See Form fields.

Show fields properties

string

required

The form field type.

string

required

The form field ID.

string

required

The form field label.

boolean

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

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

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

string

The custom event ID.

string

required

The event type. Must be filled_form.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

string

required

The form ID.

array

required

The completed form fields. See Filled form fields.

Show fields properties

string

required

The form field type. Possible values: checkbox, 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 submitted answer. Its type depends on fields.type.

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

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

array

The submitted checkbox answers.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

Response

string

required

The event ID.

string

The custom event ID.

string

required

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

string

required

The event type.

string

required

The ID of the event author.

string

required

The event visibility.

object

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

string

required

The form ID.

string

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

array

required

The completed form fields. See Filled form fields.

Show fields properties

string

required

The form field type.

string

required

The form field ID.

string

required

The form field label.

string | object | boolean

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

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

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

array

The submitted checkbox answers.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

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

string

The custom event ID.

string

required

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

string

required

The event type. Must be message.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

object

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

Show postback properties

string

required

The postback ID from the rich message event.

string

required

The ID of the thread containing the rich message event.

string

required

The ID of the rich message event.

string

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

string

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

Response

string

required

The event ID.

string

The custom event ID.

string

required

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

string

required

The event type. Always message.

string

required

The ID of the event author.

string

required

The event visibility.

string

required

The message text.

object

The rich message postback that triggered the message.

Show postback properties

string

required

The postback ID from the rich message event.

string

required

The ID of the thread containing the rich message event.

string

required

The ID of the rich message event.

string

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

string

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

object

Custom event 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",
  "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

string

The custom event ID.

string

required

The event type. Must be rich_message.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

string

required

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

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 width in pixels.

integer

The image height in pixels.

integer

The image file size in bytes.

string

The alternative text for the image.

array

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

Show elements.buttons properties

string

required

The text displayed on the button.

string

required

The behavior after a user selects the button. Possible values: webview, message, url, phone.

string

required

The button value.

string

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

string

required

The identifier that describes the action sent by send_rich_message_postback.

array

required

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

string

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

Response

string

required

The server-generated event ID.

string

The custom event ID.

string

required

The event type.

string

required

The server-generated ID of the event author.

string

required

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

string

required

The event visibility.

object

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

string

required

The template that determines how the rich message is displayed.

array

The 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 width in pixels.

integer

The image height in pixels.

integer

The image file size in bytes.

string

The alternative text for the image.

array

The buttons displayed in the rich message element.

Show elements.buttons properties

string

required

The text displayed on the button.

string

required

The behavior after a user selects the button.

string

required

The button value.

string

The webview height. Present when type is webview.

string

required

The identifier that describes the postback action.

array

required

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

string

The browsing context in which to open the URL.

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

string

The custom event ID.

string

required

The event type. Must be custom.

object

The custom JSON content.

string

default:"all"

The event visibility. Possible values: all, agents.

object

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

Response

string

required

The event ID generated by the server.

string

The custom event ID.

string

required

The event type.

string

required

The ID of the event author generated by the server.

string

required

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

object

The custom JSON content.

string

required

The event visibility.

object

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

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

string

The custom event ID.

string

required

The event type. Must be system_message.

string

The text displayed to recipients.

string

required

The system message type. See System message types.

string

The event visibility. Possible values: all, agents.

object

The variables substituted into the system message text.

Response

string

required

The event ID generated by the server.

string

The custom event ID.

string

required

The event type.

string

required

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

string

The text displayed to recipients.

string

required

The system message type. See System message types.

string

required

The event visibility.

object

The variables substituted into the system message text.

Sample System message in response

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

Users

Users represent agents and customers participating in chats.

Agent

Fields

string

required

The agent ID.

string

required

The user type. Always agent.

string

The agent’s name.

string

The agent’s email address.

boolean

If true, the agent is present in the chat.

string

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

string

required

The URL of the agent’s avatar.

string

required

The agent’s visibility. Possible values: all, agents.

Sample agent data structure

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

My profile

Fields

string

required

The agent ID.

string

required

The user type. Always agent.

string

The agent’s name.

string

The agent’s email address.

boolean

If true, the agent is present in the chat.

string

required

The URL of the agent’s avatar.

string

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

string

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

string

required

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

Sample My profile data structure

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

Customer

Fields

string

required

The customer ID.

string

required

The user type. Always customer.

string

The date and time of the most recent event created by an agent in the customer’s chats, in RFC 3339 format.

string

The URL of the customer’s avatar.

string

The date and time of the most recent event created by the customer, in RFC 3339 format.

string

The date and time when the customer’s identity was created, in RFC 3339 format.

string

The customer’s email address.

boolean

Whether the customer confirmed their email address. See Request email verification.

array

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

Show session_fields properties

string

The value of the custom session field.

string

The customer’s name.

string

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

object

The customer’s most recent visit.

Show last_visit properties

string

The date and time when the visit started, in RFC 3339 format.

string

The date and time when the visit ended, in RFC 3339 format.

string

The URL that referred the customer to the website.

string

The customer’s IP address.

string

The customer’s browser user-agent string.

object

The customer’s approximate geolocation.

Show last_visit.geolocation properties

string

The country name.

string

The ISO 3166-1 alpha-2 country code.

string

The region name.

string

The city name.

string

The IANA time zone name.

string

The latitude.

string

The longitude.

array

The pages opened during the visit.

Show last_visit.last_pages properties

string

The date and time when the page was opened, in RFC 3339 format.

string

The page URL.

string

The page title.

boolean

Whether the customer is currently connected to the chat.

object

The customer’s activity counters.

Show statistics properties

integer

The number of the customer’s chats.

integer

The number of the customer’s threads.

integer

The number of the customer’s visits.

integer

The number of the customer’s page views.

integer

The number of greetings shown to the customer.

integer

The number of greetings accepted by the customer.

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",
      "latitude": "51.1043015",
      "longitude": "17.0335007"
    },
    "last_pages": [
      {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.text.com/",
        "title": "Text - Homepage"
      },
      {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.text.com/features/ai-agent/",
        "title": "Text - AI Agents"
      }
    ]
  },
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ],
  "statistics": {
    "chats_count": 3,
    "threads_count": 9,
    "visits_count": 5,
    "page_views_count": 18,
    "greetings_shown_count": 4,
    "greetings_accepted_count": 2
  },
  "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

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

Access

Fields

array

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

Sample Access data structure

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

Chats

Fields

string

required

The chat ID.

object

The chat thread. See Threads.

array

required

The chat users. See Agent and Customer.

object

Custom chat properties organized by namespace and property name.

Show properties properties

object

The custom properties in the namespace.

Show properties.<namespace> properties

any

The custom property value.

object

The groups that can access the chat.

Show access properties

array

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

boolean

required

If true, the requester follows the chat.

Sample Chat data structure

{
  "id": "PJ0MRSHTDG",
  "thread": {
    "id": "QA37PVJ75B",
    "created_at": "2020-05-12T11:42:47.383000Z",
    "active": false,
    "user_ids": ["smith@example.com", "b7eff798-f8df-4364-8059-649c35c9ed0c"],
    "events": [
      {
        "id": "QA37PVJ75B_1",
        "created_at": "2020-05-12T11:42:47.383001Z",
        "visibility": "all",
        "type": "filled_form",
        "properties": {
          "property_namespace": {
            "property_name": "property_value"
          }
        },
        "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "custom_id": "gh4ocmtv83w",
        "form_id": "1002",
        "fields": [
          {
            "id": "10021",
            "type": "name",
            "label": "Name and Surname:",
            "answer": "Thomas Anderson"
          },
          {
            "id": "10022",
            "type": "email",
            "label": "E-mail:",
            "answer": ""
          }
        ]
      }
    ],
    "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"
    }
  ],
  "properties": {
    "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.

Fields

string

required

The chat ID.

object

A summary of the most recent thread. See Threads.

array

required

The chat users. See Agent and Customer.

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.

string

required

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

object

The event data. See Events.

object

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

object

The groups that can access the chat. See Access.

boolean

required

If true, the requester follows the chat.

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

Form fields

A component of the Form event.

Fields

array

required

The fields in the form.

Show fields properties

string

required

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

string

required

The form field ID.

string

required

The form field label.

boolean

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

array

The options available for a choice field.

Show fields.options properties

string

required

The option ID.

string

required

The option label.

Sample Form fields

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

Filled form fields

A component of the Filled form event.

Fields

array

required

The completed fields in the form.

Show fields properties

string

required

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

string

required

The form field ID.

string

required

The form field label.

any

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

Show fields.answer properties

string

required

The selected option ID.

string

required

The selected option label.

integer

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

array

The answers to a multi-value field.

Show fields.answers properties

string

required

The selected option ID.

string

required

The selected option label.

Sample Filled form fields

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

Properties

Properties are key-value stores. You can set them on a chat, thread, or event. For more information, see the Configuration API documentation.

Fields

object

The custom properties in the namespace.

Show properties.<namespace> properties

any

The custom property value.

Sample Properties data structure

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

Threads

Fields

string

required

The thread ID.

object

The groups that can access the thread.

Show access properties

array

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

boolean

required

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

array

The IDs of users participating in the thread.

array

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

Show events properties

string

required

The event ID.

string

The custom event ID.

string

required

The event type.

string

required

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

string

The ID of the event author.

string

required

The event visibility. Possible values: all, agents.

string

The message text. Present for message events.

object

Custom event properties organized by namespace and property name.

Show events.properties properties

object

The custom event properties in the namespace.

Show events.properties.<namespace> properties

any

The custom event property value.

object

Custom thread properties organized by namespace and property name.

Show properties properties

object

The custom thread properties in the namespace.

Show properties.<namespace> properties

any

The custom thread property value.

string

The reason access to the thread is restricted.

object

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

Show queue properties

integer

required

The chat’s position in the queue.

integer

required

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

string

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

integer

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

string

The preceding thread ID.

string

The following thread ID.

string

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

string

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

string

required

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

array

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

Sample Thread data structure

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

Sample restricted Thread data structure

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

Overview

Chats

Chat access

Chat users

Events

Properties

Thread tags

Customers

Status

Other

Configuration

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