Data structures

This document contains a reference of data structures available in the LiveChat 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

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

File event informs about a file being uploaded.

Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`file`
`properties`	no	`object`	Properties
`url`	yes	`string`	Has to point to the LiveChat CDN. It's recommended to use the URL returned by `upload_file`.

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
`properties`	optionally
`name`	always
`url`	always
`thumbnail_url`, `thumbnail2x_url`	only for images
`content_type`	always
`size`, `width`, `height`	only for images

Sample File in response

Copied!

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

Filled form

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

Request

Parameter	Required	Data type	Notes
`custom_id`	no	`string`
`type`	yes	`string`	`filled_form`
`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
`properties`	optionally
`form_id`	always
`fields`	always	An array of filled form fields

Sample Filled form in response

Copied!

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

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

Copied!

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

Rich message event contains rich message data structure. Read more in a document dedicated to Rich messages.

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`
`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`.
`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`. More...
`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. More...
`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`. More...
`elements.buttons.user_ids`	yes	`array`	Describes users that sent the postback with `"toggled": true`.

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

Sample Rich message in response

Copied!

{
	"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
			},
			"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": []
				}
			]
		}
	]
}

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
`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
`properties`	optionally

Sample Custom event in response

Copied!

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

System message event is a 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
`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

Sample System message in response

Copied!

{
	"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 are another important data structure. Within this data structure type, we can distinguish:

Customer

Sample Customer data structure

Copied!

{
	"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"type": "customer",
	"name": "Thomas Anderson",
	"email": "t.anderson@example.com",
	"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"
}

Field	Req./Opt.	Notes
`avatar`	optional
`email`	optional
`name`	optional
`session_fields`	optional	An array of custom object-enclosed `key:value` pairs. Available for the session duration.

Agent

Sample Agent data structure

Copied!

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

Other common structures

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

Access

Sample Access data structure

Copied!

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

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

Chats

Sample Chat data structure

Copied!

{
	"id": "PJ0MRSHTDG",
	"threads": [
		{
			"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"
					}
				}
			],
			"properites": {
				"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
		]
	},
	"properites": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

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

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.

Sample Chat summary data structure

Copied!

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

Filled form fields

A component of the Filled form event.

Sample Filled form fields

Copied!

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

Field	Required	Data type	Notes
`fields`	yes	`array of objects`	The fields a form contains.
`type`	yes	`string`	Possible values: `checkbox`, `email`, `name`, `question`, `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`

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

Copied!

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

Threads

Sample Thread data structure

Copied!

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

Field	Req./Opt.	Note
`access`	optional
`active`	required	Possible values: `true` (thread is still active) or `false`(thread no longer active).
`events`	optional
`properties`	optional
`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.
`created_at`	required	Date & time format with a resolution of microseconds, `UTC string`. Generated server-side.

Data structures.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

File

Request

Response

Filled form

Request

Response

Message

Request

Response

Rich message

Request

Response

Custom

Request

Response

System message

Request

Response

Users

Customer

Agent

Other common structures

Access

Chats

Chat summaries

Filled form fields

Properties

Threads

Data structures