Platform
APIs & SDKs
Resources

...

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

ParameterRequiredData typeNotes
custom_idnostring
typeyesstringfile
propertiesnoobjectProperties
urlyesstringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file.
alternative_textnostringOnly applicable to images

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
namealways
urlalways
thumbnail_url, thumbnail2x_urlonly for images
content_typealways
size, width, heightonly for images
alternative_textonly 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,
	"alternative_text": "A sample image"
}

Form

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

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringform
propertiesnoobjectProperties
form_idyesstring
fieldsyesarrayThe fields a form contains. See form fields for details.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idoptionallyIf form is generated by system, then this field is omitted.
propertiesoptionally
form_idalways
form_typeoptionallyThe 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).
fieldsalwaysAn array of form fields
Sample Form in response
Copied!
{
	"id": "157986144052005549",
	"fields": [
		{
			"id": "157986144052003238",
			"type": "header",
			"label": "Welcome to our LiveChat! Please fill in the form below before starting the chat."
		},
		{
			"id": "157986144052008371",
			"type": "name",
			"label": "Name:",
			"required": false
		},
		{
			"id": "157986144052005782",
			"type": "email",
			"label": "E-mail:",
			"required": false
		},
		{
			"id": "157986144052009331",
			"type": "group_chooser",
			"label": "Choose a department:",
			"required": true,
			"options": [
				{
					"id": "0",
					"group_id": 1,
					"label": "Marketing"
				},
				{
					"id": "1",
					"group_id": 2,
					"label": "Sales"
				},
				{
					"id": "2",
					"group_id": 0,
					"label": "General"
				}
			]
		}
	]
}

Filled form

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

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfilled_form
recipientsyesstringPossible values: all (default), agents
propertiesnoobjectProperties
form_idyesstring
fieldsyesarrayThe fields a form contains. See filled form fields for details.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
propertiesoptionally
form_idalways
form_typeoptionallyThe 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).
fieldsalwaysThe fields a form contains. See filled form fields for details.
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

ParameterRequiredData typeNotes
custom_idnostring
textyesstringMax. 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.
typeyesstringmessage
propertiesnoobjectProperties
postbacknoobjectIndicates that the message event was generated in response to a rich message event.
postback.idyesstringID of the postback from the rich message event.
postback.thread_idyesstringID of the thread with the rich message event.
postback.event_idyesstringID of the rich message event.
postback.typenostringShould be used together with postback.value (when one of them is present, the other is required).
postback.valuenostringShould be used together with postback.type (when one of them is present, the other is required).

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealwaysmessage
author_idalways
textalways
postbackoptionallyAppears in a message only when triggered by a rich message.
postback.idalways
postback.thread_idalways
postback.event_idalways
postback.typeoptionallyAppears only if postback.value is present.
postback.valueoptionallyAppears only if postback.type is present.
propertiesoptionallyProperties
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

ParameterRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
propertiesnoobjectThe properties data structure
template_idyesstringDefines how every Rich Message will be presented. Values: cards, sticker, or quick_replies.
elementsnoarrayCan contain up to 10 element objects.
elements.titleyesstringDisplays formatted text on RMs.
elements.subtitleyesstringDisplays formatted text on RMs.
elements.imageyesimageDisplays images on RMs. Required param: url; Optional params: name, content_type, size, width, height, alternative_text.
elements.buttonsnoarrayDisplays buttons. Can contain up to 13 button objects.
elements.buttons.textyesstringText displayed on a button.
elements.buttons.typeyesstringDefines 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.valueyesstringShould 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_heightyesstringRequired only for the webview buttontype. Possible values: compact, full, tall.
elements.buttons.postback_idyesstringA description of the sent action. Describes the action sent via send_rich_message_postback. More...
elements.buttons.user_idsyesarrayDescribes users that sent the postback with "toggled": true.
elements.buttons.targetnostringShould 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

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string. Generated server-side.
propertiesoptionally
template_idalways
elementsoptionally
elements.titlealways
elements.subtitlealways
elements.imagealways
elements.buttonsoptionally
elements.buttons.textalways
elements.buttons.typealways
elements.buttons.valuealways
elements.buttons.webview_heightalwaysUnless button type is different than webview.
elements.buttons.postback_idalways
elements.buttons.user_idsalways
elements.buttons.targetoptionally
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,
				"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

ParameterRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
propertiesnoobjectThe properties data structure

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
contentoptionally
propertiesoptionally
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

ParameterRequiredData typeNotes
custom_idnostringYou can give the system message a custom ID.
typeyesstringsystem_message
textnostringText displayed to recipients
system_message_typeyesstringSystem message type
text_varsnoobjectVariables used in the text

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
textoptionally
system_message_typealways
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",
	"email_verified": false,
	"avatar": "https://example.com/avatar.png",
	"session_fields": [
		{
			"custom_key": "custom_value"
		},
		{
			"another_custom_key": "another_custom_value"
		}
	],
	"present": true,
	"events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.Notes
avataroptional
emailoptional
email_verifiedoptionalSpecifies if the customer confirmed their email address. See Request Email Verification.
nameoptional
session_fieldsoptionalAn 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
		]
	}
}
FieldReq./Opt.Note
group_idsrequiredgroup 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"
		}
	}
}
FieldReq./Opt.Note
propertiesoptional
accessoptional

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
}

Forms

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

Sample Form data structure
Copied!
{
	"id": "157986144052005549",
	"fields": [
		{
			"id": "157986144052003238",
			"type": "header",
			"label": "Welcome to our LiveChat! Please fill in the form below before starting the chat."
		},
		{
			"id": "157986144052008371",
			"type": "name",
			"label": "Name:",
			"required": false
		},
		{
			"id": "157986144052005782",
			"type": "email",
			"label": "E-mail:",
			"required": false
		},
		{
			"id": "157986144052009331",
			"type": "group_chooser",
			"label": "Choose a department:",
			"required": true,
			"options": [
				{
					"id": "0",
					"group_id": 1,
					"label": "Marketing"
				},
				{
					"id": "1",
					"group_id": 2,
					"label": "Sales"
				},
				{
					"id": "2",
					"group_id": 0,
					"label": "General"
				}
			]
		}
	]
}
FieldRequiredData typeNotes
idnostringForm ID
fieldsyesarray of objectsThe fields a form contains
fields.typeyesstringPossible values: header, checkbox, email, name, question, subject, textarea, group_chooser, radio, select
fields.idnostringField ID, for all field types
fields.labelyesstringField label, for all field types
fields.requirednoboolDetermines whether the answer for given field is required, for all field types except header
fields.optionsnoarray of objectsFor checkbox, group_chooser, radio and select
fields.options.idyesstringAn identifier of each option a Customer can choose
fields.options.labelyesstringAnswer label
fields.options.group_idyesnumberFor group_chooser

Form fields

A component of the Form event.

Sample Form fields
Copied!
{
	"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"
		}
	]
}
FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, subject, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types

Filled form fields

A component of the Filled form event.

Sample 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"
			}
		}
	]
}
FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, subject, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types
answeryesanyFor all field types
answer.idyesstringAn identifier of each option a Customer can choose. For all field types.
answer.labelyesstringAnswer label; for all field types
answer.group_idyesnumberFor 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"
}
FieldReq./Opt.Note
accessoptional
activerequiredPossible values: true (thread is still active) or false(thread no longer active).
eventsoptional
propertiesoptional
queueoptionalPresent only if the chat is in the queue. The wait time for an available agent is approximated in seconds.
previous_thread_idoptionalPresent only if there is a preceding thread.
next_thread_idoptionalPresent only if there is a following thread.
created_atrequiredDate & time format with a resolution of microseconds, UTC string. Generated server-side.

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@text.com