API version

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
recipientsyesstringPossible values: all (default), agents
propertiesnoobjectProperties
urlyesstringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file.

Response

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

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

Request

ParameterRequiredData 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
recipientsalways
propertiesoptionally
form_idalways
fieldsalwaysAn 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",
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"properties": {},
	"form_id": "1473433500211",
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name",
			"answer": "John Doe"
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email",
			"answer": "customer1@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": {
				"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
recipientsyesstringPossible 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
recipientsalways
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"
	},
	"recipients": "all",
	"properties": {}
}

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
recipientsyesstringThose who can display the rich message: all (default) or 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.
elements.buttonsnoarrayDisplays buttons. Can contain up to 11 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.
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.

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.
recipientsalways
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
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",
	"recipients": "all",
	"properties": {},
	"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

ParameterRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
recipientsyesstringThose who can receive the custom event: all (default) or 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
recipientsalways
propertiesoptionally
Sample Custom 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"
		}
	},
	"recipients": "all",
	"properties": {}
}

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
recipientsnostringIt 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
recipientsoptionally
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",
	"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": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@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"
}
FieldReq./Opt.Note
routing_statusoptionalReturned only if the Agent is currently logged in.

My profile

Sample My profile data structure
Copied!
{
  "id": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@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

Sample Customer data structure
Copied!
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "example.com/avatars/1.png",
  "last_visit": {
    "started_at": "2017-10-12T15:19:21.010200Z",
    "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"
      }
    ]
  },
  "fields": {
    "custom field name": "custom field value"
  },
  "statistics": {
    "chats_count": 3,
    "threads_count": 9,
    "visits_count": 5
  },
  "__priv_lc2_customer_id": "test_771305.dafea66e5c", //old customer_id
  "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, // optional, applies only to customer located in chat object
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.Notes
agent_last_event_created_atoptional
avataroptional
customer_last_event_created_atoptional
created_atoptional
emailoptional
fieldsoptionalIs not present when the chat is archived.
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",
  "users": [
    // array of "User" objects
  ],
  "threads": [
    // optional
    // "Thread" object
  ],
  "threads_summary": [
    {
      "thread_id": "K600PKZON8",
      "order": 129846129847
    },
    {
      "thread_id": "K600PKZON8",
      "order": 129846129848
    }
  ],
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "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",
  "users": [
    // array of "User" objects
  ],
  "last_event_per_type": {
    // last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_order": 3,
      "event": {
        // "restricted_access": true
        // or
        // "Event > Message" object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON6",
      "thread_order": 1,
      "event": {
        // "restricted_access": true
        // or
        // "Event > System message" object
      }
    }
    // ...
  },
  "last_thread_summary": {
    "id": "K600PKZON8",
    "order": 3,
    "timestamp": 1473433500,
    "user_ids": ["agent1@example.com"],
    "properites": {
      // "Properites" object
    },
    "tags": ["bug_report"]
  },
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": false
}

Filled form fields

A component of the Filled form event.

FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types
answeryesanyFor all field types
answer.idyesstringAnswer id; for all field types
answer.labelyesstringAnswer label; for all field types
answer.group_idyesnumberFor group_chooser
Response
Copied!
{
    "fields": [{
        "type": "name",
        "id": "154417206262603539",
        "label": "Your name",
        "answer": "John Doe"
    }, {
        "type": "email",
        "id": "154417206262601584",
        "label": "Your email",
        "answer": "customer1@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": {
            "group_id": 1,
            "label": "Marketing"
        }
    }]
}

Properties

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

Sample Properties data structure
Copied!
{
  "properties": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure
Copied!
{
  "id": "K600PKZON8",
  "timestamp": 1473433500,
  "active": true,
  "user_ids": ["agent1@example.com"],
  "restricted_access": true,
  "events": [
    // array of "Event" objects
  ],
  "order": 112057129857,
  "properties": {
    // "Properties" object
  },
  "access": {
    // "Access" object
  }
}
FieldReq./Opt.Note
accessoptional-
activerequiredPossible values: true (thread is still active) or false(thread no longer active)
eventsoptionalDoesn't exists if restricted_access is true.
propertiesoptional-
restricted_accessoptional-