Platform
APIs & SDKs
Resources

...

Data structures

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

The File event informs about an uploaded file.

Request

ParameterRequiredData typeNotes
custom_idnostring
typeyesstringfile
visibilitynostringPossible values: all (default), agents
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
visibilityalways
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",
	"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 the LiveChat app, but you can leverage this feature in a custom chatting solution.

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringform
visibilitynostringPossible values: all (default), agents
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_idalways
visibilityalways
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

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.

Gather contact info with LiveChat form event
Sample 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": "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

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfilled_form
visibilitynostringPossible 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
visibilityalways
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",
	"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

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
visibilitynostringPossible values: all (default), agents
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
visibilityalways
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",
	"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. Read more about rich messages.

Request

ParameterRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
visibilitynostringPossible values: all (default), agents
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.
visibilityalways
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",
	"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

ParameterRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
visibilitynostringPossible values: all (default), agents
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
visibilityalways
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"
		}
	},
	"visibility": "all",
	"properties": {
		"property_namespace": {
			"property_name": "property_value"
		}
	}
}

System message

System message event is 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
visibilitynostringIt can be specified when sending system messages via the Send Event method. Possible values: all, agents.
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
visibilityalways
Sample System message in response
Copied!
{
	"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

Sample Agent data structure
Copied!
{
	"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"
}
FieldReq./Opt.Notes
visibilityrequiredPossible values: all or agents

My profile

Sample My profile data structure
Copied!
{
	"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"
}
FieldReq./Opt.Notes
routing_statusoptional
events_seen_up_tooptionalRFC 3339 datetime string; the timestamp of the most recent event seen by the Agent—all the previous events are considered seen.

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/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.livechat.com/",
				"title": "LiveChat - Homepage"
			},
			{
				"opened_at": "2017-10-12T15:19:21.010200Z",
				"url": "https://www.livechat.com/tour",
				"title": "LiveChat - Tour"
			}
		]
	},
	"session_fields": [
		{
			"custom_key": "custom_value"
		},
		{
			"another_custom_key": "another_custom_value"
		}
	],
	"statistics": {
		"chats_count": 3,
		"threads_count": 9,
		"visits_count": 5
	},
	"__priv_lc2_customer_id": "test_771305.dafea66e5c",
	"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",
	"followed": false,
	"online": true,
	"group_ids": [
		0
	],
	"state": "browsing"
}
FieldReq./Opt.Notes
agent_last_event_created_atoptional
avataroptional
customer_last_event_created_atoptional
created_atoptional
emailoptional
email_verifiedoptionalSpecifies if the customer confirmed their email address. See Request Email Verification.
session_fieldsoptionalAn array of custom object-enclosed key:value pairs. Expires along with the session.
nameoptional
events_seen_up_tooptionalRFC 3339 datetime string
last_visitoptional
presentoptional
statisticsoptional

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": "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
}
FieldReq./Opt.
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_thread_summary and last_event_per_type.

Sample Chat summary data structure
Copied!
{
	"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.

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": [
		"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"
}
FieldReq./Opt.Note
accessoptional
activerequiredPossible values: true (thread is still active) or false(thread no longer active)
eventsoptionalDoesn't exists if restricted_access is present.
propertiesoptional
restricted_accessoptionalContains the reason for access restriction.
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.
previous_accessible_thread_idoptionalPresent only if there is a preceding thread accessible for the requester. Field present only in list_archives.
next_accessible_thread_idoptionalPresent only if there is a following thread accessible for the requester. Field present only in list_archives.
created_atrequiredDate & time format with a resolution of microseconds, UTC string. Generated server-side.
tagsoptionalAn array of tags. Returned only if a thread was tagged.
customer_visitoptionalContains details about customer visit (IP, User Agent and geolocation).

...

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