# Agent Chat API * [Introduction](#introduction) * [Web API](#web-api) * [Real-Time Messaging API](#real-time-messaging-api) * [Authentication](#authentication) * [Events order](#events-order) * [Examples](#examples) * [JavaScript](#javascript) * [Go](#go) * [Python](#python) * [Objects](#objects) * [Thread](#thread) * [User](#user) * [Event](#event) * [Typing indicator](#typing-indicator) * [Sneak peek](#sneak-peek) * [Ban](#ban) * [Scopes](#scopes) * [Properties](#properties) * [Errors handling](#errors-handling) * [Format](#format) * [Possible errors](#possible-errors) * [Methods](#methods) * [Login](#login) * [Get archives](#get-archives) * [Get filtered chats](#get-filtered-chats) * [Get chat threads](#get-chat-threads) * [Start chat](#start-chat) * [Join chat](#join-chat) * [Remove from chat](#remove-from-chat) * [Send event](#send-event) * [Send rich message postback](#send-rich-message-postback) * [Multicast](#multicast) * [Send typing indicator](#send-typing-indicator) * [Ban customer](#ban-customer) * [Close thread](#close-thread) * [Update chat scopes](#update-chat-scopes) * [Update agent](#update-agent) * [Change push notifications](#change-push-notifications) * [Update chat properties](#update-chat-properties) * [Update chat thread properties](#update-chat-thread-properties) * [Update last seen timestamp](#update-last-seen-timestamp) * [Add auto chat scopes](#add-auto-chat-scopes) * [Remove auto chat scopes](#remove-auto-chat-scopes) * [Get auto chat scopes config](#get-auto-chat-scopes-config) * [Upload image](#upload-image) * [Pushes](#pushes) * [Incoming chat thread](#incoming-chat-thread) * [Chat users updated](#chat-users-updated) * [Incoming event](#incoming-event) * [Incoming rich message postback](#incoming-rich-message-postback) * [Incoming multicast](#incoming-multicast) * [Incoming typing indicator](#incoming-typing-indicator) * [Incoming sneak peek](#incoming-sneak-peek) * [Customer banned](#customer-banned) * [Thread closed](#thread-closed) * [Chat scopes updated](#chat-scopes-updated) * [Customer updated](#customer-updated) * [Agent updated](#agent-updated) * [Agent disconnected](#agent-disconnected) * [Chat properties updated](#chat-properties-updated) * [Chat thread properties updated](#chat-thread-properties-updated) * [Last seen timestamp updated](#last-seen-timestamp-updated)

Introduction

This documentation describes version v0.5 of agent-api.

Throughout the text we will use the term "client" to describe a service (an application, a script, an integration, etc.) which uses chat.io Agent API.

Web API

Web API is similar to REST API. A client can send a request message that results in getting a response message.

Requests

API endpoint

HTTP method Endpoint
POST https://api.chat.io/agent/v0.5/action/<action>

Required headers

Header Value Notes
Content-Type multipart/form-data; boundary=<boundary> Valid for send_file action
application/json Valid for every action except upload_image
Authorization Bearer <token> Access token

Messages format

Request

{
	"payload": {
		// optional
	},
	"author_id": "<author_id>" // optional, applies only to bots
}

Real-Time Messaging API

Real-Time Messaging API (RTM API) is based on a websocket-like connection. A client can send request message that results in getting response message. It can also get push messages anytime.

Connection

API endpoints

Transport Endpoint
socket.io https://api.chat.io/agent/v0.5/rtm/sio
websocket wss://api.chat.io/agent/v0.5/rtm/ws
Example
https://api.chat.io/agent/v0.5/rtm/ws

Ping

A client should ping the server each 15 seconds, otherwise the connection will be closed after about one minute of inactivity. If control frame ping is unavailable (in web browsers), a client should use a protocol message with ping action.

Messages format

Request

{
	"request_id": "<request_id>", // optional
	"action": "<action>",
	"payload": {
		// optional
	},
	"author_id": "<author_id>" // optional, applies only to bots
}

Response

{
	"request_id": "<request_id>", // optional
	"action": "<action>",
	"type": "response",
	"success": true,
	"payload": {
		// optional
	}
}

Push

{
	"request_id": "<request_id>", // optional, applies only to the requester
	"action": "<action>",
	"type": "push",
	"payload": {
		// optional payload
	}
}

Authentication

Agent authentication is handled by access tokens. See how to obtain an access token in Authorization section.

All authorization scopes are defined here. Each action in Agent API describes required scopes.

Events order

Chat messages are not guaranteed to be sorted by server. A client should sort them by order parameter. Do not use timestamp to sort messages because two events can have the same timestamp.

Examples

All examples have a similar structure: they connect and log in to Agent API and then start a chat by sending a welcome message (via Websocket).

JavaScript

Sample file: examples/example.js

Go

Sample file: examples/example.go

Remember to install the proper lib:

go get github.com/gorilla/websocket

Python

Sample file: examples/example.py

Remember to install the proper lib:

sudo pip install websocket-client

Objects

Objects are standardized data formats that are used in API requests and responses.

Thread

{
	"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"timestamp": 1473433500,
	"active": true,
	"user_ids": ["john@gmail.com"],
	"events": [
		// array of "Event" objects
	],
	"order": 112057129857,
	"properties": {
		// "Properties" object
	}
}
  • active can take the following values:
    • true (thread is still active)
    • false (thread no longer active)
  • properties is optional

User

Customer

{
	"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"type": "customer",
	"name": "John Smith",
	"email": "john@gmail.com",
	"present": true,
	"last_seen_timestamp": 1473433500,
	"monitoring": {
		"current_visit": {
			"start": 1474659379,
			"pages": [{
					"start": 1474659379,
					"url": "https://www.livechatinc.com/",
					"title": "LiveChat - Homepage"
				},
				{
					"start": 1474659393,
					"url": "https://www.livechatinc.com/tour",
					"title": "LiveChat - Tour"
				}
			]
		},
		"stats": {
			"visits": 16,
			"threads": 7,
			"page_views": 29,
			"last_visit": 1474636646
		},
		"referrer": "http://www.google.com/",
		"ip": "194.181.146.130",
		"host": "87-99-47-205.internetia.net.pl",
		"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"
		}
	},
	"fields": {
		"custom field name": "custom field value"
	},
	"banned": false
}

Optional properties:

  • name
  • email
  • last_seen_timestamp
  • monitoring
  • properties

Agent

{
	"id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
	"type": "agent",
	"name": "Support Team",
	"email": "john@gmail.com",
	"present": true,
	"last_seen_timestamp": 1473433500,
	"avatar": "cdn.livechatinc.com/avatars/1.png",
	"routing_status": "accepting_chats"
}

routing_status will be returned only if the agent is currently logged in.

My profile

{
	"id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
	"type": "agent",
	"name": "Support Team",
	"email": "john@gmail.com",
	"present": true,
	"last_seen_timestamp": 1473433500,
	"avatar": "cdn.livechatinc.com/avatars/1.png",
	"routing_status": "accepting_chats",
	"permission": "administrator"
}

Event

Message

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"text": "hello there",
	"recipients": "all",
	"properties": {
		// "Properties" object
	}
}
  • recipients can take the following values: all (default), agents
  • custom_id is optional
  • properties is optional

System message

It cannot be sent by a user.

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "system_message",
	"timestamp": 1473433500, // generated server-side
	"text": "hello there",
	"recipients": "all"
}
  • recipients can take the following: values: all (default), agents
  • custom_id is optional

Annotation

An annotation does not create a new thread. It just adds an event to the last thread without extending thread duration.

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "annotation",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"text": "Sample annotation",
	"recipients": "all",
	"annotation_type": "rating",
	"properties": {
		// "Properties" object
	}
}
  • recipients can take the following values: all (default), agents
  • custom_id is optional
  • properties is optional

Filled form

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 4, // generated server-side
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"recipients": "all",
	"properties": {
		// "Properties" object
	},
	"fields": [{
			"type": "text",
			"name": "name",
			"label": "Your name",
			"required": true,
			"value": "Jan Kowalski"
		},
		{
			"type": "email",
			"name": "email",
			"label": "Your email",
			"required": true,
			"value": "jan.kowalski@gmail.com"
		},
		{
			"type": "radio",
			"name": "purpose",
			"label": "Chat purpose",
			"required": true,
			"options": [{
					"label": "Support",
					"value": "support",
					"checked": true
				},
				{
					"label": "Sale",
					"value": "sale",
					"checked": false
				}
			]
		},
		{
			"type": "checkbox",
			"name": "industry",
			"label": "Company industry",
			"required": true,
			"options": [{
				"label": "automotive",
				"value": "automotive",
				"checked": true
			}, {
				"label": "IT",
				"value": "it",
				"checked": true
			}]
		},
		{
			"type": "select",
			"name": "country",
			"label": "Country",
			"required": true,
			"options": [{
				"label": "USA",
				"value": "usa",
				"checked": false
			}, {
				"label": "Poland",
				"value": "pl",
				"checked": true
			}]
		}
	]
}
  • recipients can take the following values: all (default), agents
  • custom_id is optional
  • properties is optional

File

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "file",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"recipients": "all",
	"properties": {
		// "Properties" object
	},
	"name": "image25.png",
	"url": "https://domain.com/asdsfdsf.png",
	"content_type": "image/png",
	"size": 123444,
	"width": 640,
	"height": 480
}
  • recipients can take the following values: all (default), agents
  • properties is optional
  • custom_id is optional

Custom

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "custom",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"content": {
		"custom": {
			"nested": "json"
		}
	},
	"recipients": "all",
	"properties": {
		// "Properties" object
	}
}
  • recipients can take the following values: all (default), agents,
  • custom_id is optional
  • properties is optional

Rich message

{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "12345-bhdsa",
	"order": 1, // generated server-side
	"type": "rich_message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"timestamp": 1473433500, // generated server-side
	"recipients": "all",
	"properties": {
		// "Properties" object
	},
	"template_id": "cards",
	"elements": [{
		"title": "Lorem ipsum dolor.",
		"subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
		"image": {
			"name": "image25.png",
			"url": "https://domain.com/asdsfdsf.png",
			"content_type": "image/png",
			"size": 123444,
			"width": 640,
			"height": 480
		},
		"buttons": [{
			"text": "yes",
			"postback_id": "action_yes",
			"user_ids": ["a7eef798-f8df-4364-8059-649c35c9ed0e", "a7qef880-aaaa-4364-8059-649c35c9ed0q"]
		}, {
			"text": "no",
			"postback_id": "action_no",
			"user_ids": []
		}]
	}, {
		"title": "Lorem ipsum dolor 2."
	}]
}
  • custom_id, properties and elements are optional
  • elements may contain 1-10 element objects
  • all elements properties are optional: title, subtitle, image and buttons
  • image properties (expect for url) are optional: name, url, content_type, size, width and height
  • buttons may contain 1-10 button objects

  • template_id describes how the event should be presented in an app

  • elements.buttons.postback_id describes the action sent via send_rich_message_postback method

  • multiple buttons (even from different elements) can contain the same postback_id; calling send_rich_message_postback with this id will add user to all these buttons at once.

  • elements.buttons.user_ids describes users that sent the postback with "toggled": true

Typing indicator

{
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"recipients": "all",
	"timestamp": 1473433500
}

Sneak peek

{
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"recipients": "agents",
	"timestamp": 1473433500,
	"text": "hello there"
}

Ban

{
	"days": 5
}
  • days - the number of days the ban will last

Scopes

An empty object designates no scope, which means that all agents can see it.

 {
	"scopes": {
		"groups": [1, 2]
	}
}

Properties

This section describes properties object format only, to read more about properties click [here](https://www.chat.io/docs/apis-overview/#properties).

General format

{
	"<property_namespace>": {
		"<property_name>": {
			"value": <property_value> // <property_value> type depends on the property configuration
		}
	}
}

Sample properties

{
	"properties": {
		"rating": {
			"score": {
				"value": 1
			},
			"comment": {
				"value": "rated good!"
			}
		},
		"routing": {
			"idle": {
				"value": false
			}
		}
	}
}

Errors handling

Format

Error payload

{
	"error": {
		"type": "authentication",
		"message": "Authentication error"
	}
}

Possible errors

Type Default Message Notes
internal Internal server error
validation Wrong format of request
authorization Authorization error Agent is not allowed to perform action
authentication Authentication error Invalid / expired access token
request_timeout Request timeouted Timeout threshold is 15 seconds
license_expired License expired
unsupported_version Unsupported version Unsupported version of protocol

Methods

Login

It returns current agent’s initial state.

Action RTM API Web API Push message
login - -

No persmission is required to perform this action.

Request payload

Request object Required Notes
token Yes SSO Token
reconnect No Reconnecting sets status to last known state instead of default
push_notifications.firebase_token No Firebase device token to allow connecting this instance with existing push notification instance (to be seen as 1 instance)
push_notifications.platform Yes OS platform
application.name No Application name
application.version No Application version
  • <platform> can take the following values:
    • ios - iOS operating system
    • android - Android operating system

Sample request payload

{
	"push_notifications": {
		"firebase_token": "JDa8813Ka92mmKda00dsdkAKDA0",
		"platform": "ios"
	},
	"application": {
		"name": "SmartClient - Chrome",
		"version": "4.1.2.1231 (57.0.2987.133)"
	}
}

Sample response payload

{
	"license": {
		"id": "123",
		"plan": "enterprise",
		"expiration_timestamp": 1483433500,
		"creation_timestamp": 1482433500,
		"in_trial": true
	},
	"my_profile": {
		// "User > My profile" object
	},
	"chats_summary": [{
		"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
		"users": [
			// array of "User" objects
		],
		"last_event_per_type": { // the last event of each type in chat
			"message": {
				"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
				"thread_order": 343544565,
				"event": {
					// "Event > Message" object
				}
			},
			"system_message": {
				"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
				"thread_order": 343544565,
				"event": {
					// "Event > System message" object
				}
			},
			...
		},
		"last_thread_summary": {
			"id": "OE070R0W0U",
			"timestamp": 1473433500,
			"user_ids": ["john@gmail.com"],
			"order": 12417249812721,
			"properties": {
				"routing": {
					"idle": {
						"value": false
					},
					"unassigned": {
						"value": false
					}
				},
				...
			}
		},
		"properties": {
			"routing": {
				"idle": {
					"value": false
				},
				"unassigned": {
					"value": false
				}
			},
			...
		},
		"scopes": {
			// "Scopes" object
		}
	}]
}
  • properties is optional
  • scopes is optional

Get archives

It returns active threads that the current agent has access to.

Action RTM API Web API Push message
get_archives - -

Permissions

  • chats--all:read - read access for all license chats

Request payload

Request object Required Notes
filters.query No
filters.date_from No YYYY-MM-DD format
filters.date_to No YYYY-MM-DD format
filters.agent_ids No Array of agent IDs
filters.team_ids No Array of team IDs
filters.properties.<namespace>.<name>.<filter_type> No
pagination.page No
pagination.limit No
  • <filter_type> can take the following values (only one is allowed for single property):
    • exists (bool)
    • values (type[] - array with specific type for property: string, int or bool)
    • exclude_values (type[] - array with specific type for property: string, int or bool)

Sample request payload

{
	"filters": {
		"query": "search keyword",
		"agents": ["p.bednarek@livechatinc.com"],
		"date_from": "2016-09-01",
		"date_to": "2016-10-01",
		"properties": {
			"rating": {
				"score": {
					"values": [1]
				}
			},
			"rating": {
				"comment": {
					"exists": true
				}
			}
		}
	},
	"pagination": {
		"page": 1,
		"limit": 25
	}
}

Sample response payload

{
	"chats": [{
		"chat": {
			"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
			"users": [
				// array of "User" objects          
			],
			"thread": {
				// "Thread" object          
			}
		}
	}],
	"pagination": {
		"page": 1,
		"total": 3
	}
}

Get filtered chats

Action RTM API Web API Push message
get_filtered_chats - -

Permissions

  • chats--all:read - read access for all license chats
  • chats--my:read - read access for the chats requester belong to

Request payload

Request object Required Notes
filters.include_active No
filters.properties.<namespace>.<name>.<filter_type> No
  • <filter_type> can take the following values (only one is allowed for single property):
    • exists (bool)
    • values (type[] - array with specific type for property: string, int or bool)
    • exclude_values (type[] - array with specific type for property: string, int or bool)

Sample request payload

{
	"filters": {
		"properties": {
			"rating": {
				"score": {
					"values": [1]
				}
			},
			"rating": {
				"comment": {
					"exists": true
				}
			}
		},
		"include_active": false
	}
}

Sample response payload

{
	"chats_summary": [{
		"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
		"users": [
			// array of "User" objects
		],
		"last_event_per_type": { // last event of each type in chat
			"message": {
				"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
				"thread_order": 343544565,
				"event": {
					// "Event > Message" object
				}
			},
			"system_message": {
				"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
				"thread_order": 343544565,
				"event": {
					// "Event > System message" object
				}
			},
			...
		},
		"last_thread_summary": {
			"id": "OE070R0W0U",
			"timestamp": 1473433500,
			"user_ids": ["john@gmail.com"],
			"order": 12417249812721,
			"properties": {
				"routing": {
					"idle": {
						"value": false
					},
					"unassigned": {
						"value": false
					}
				},
				...
			}
		},
		"properties": {
			"routing": {
				"idle": {
					"value": false
				},
				"unassigned": {
					"value": false
				}
			},
			...
		},
		"scopes": {
			// "Scopes" object
		}
	}]
}

Get chat threads

It returns threads that the current agent has access to in a given chat.

Action RTM API Web API Push message
get_chat_threads - -

Permissions

  • chats--all:read - read access for all license chats
  • chats--my:read - read access for the chats requester belong to

Request payload

Request object Required Notes
chat_id Yes
thread_ids No

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"thread_ids": ["a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5"]
}

Sample response payload

{
	"chat": {
		"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
		"users": [
			// array of "User" objects         
		],
		"threads": [ // optional
			// "Thread" object
		],
		"threads_summary": [{
				"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
				"order": 129846129847
			},
			{
				"thread_id": "b0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
				"order": 129846129848
			}
		],
		"properites": {
			// "Properites" object
		},
		"scopes": {
			// "Scopes" object
		}
	}
}

Start chat

Starts a chat.

Action RTM API Web API Push message
start_chat incoming_chat_thread

No persmission is required to perform this action.

Request payload

Request object Required Notes
chat.properties No Initial chat properties
chat.thread.events No Initial chat events array
chat.thread.properties No Initial chat thread properties

Sample request payload

{
	"chat": {
		"properties": {
			"source": {
				"type": "facebook"
			},
			...
		},
		"thread": {
			"events": [{
				"type": "message",
				"custom_id": "12312.301231238591134",
				"text": "hello there",
				"recipients": "all"
			}, {
				"type": "system_message",
				"custom_id": "12312.301231238591135",
				"text": "hello there",
				"recipients": "agents"
			}],
			"properties": {
				"source": {
					"type": "facebook"
				},
				...
			}
		}
	}
}

Sample response payload

{
	"chat": {
		"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
		"users": [
			// array of "User" objects
		],
		"thread": {
			// "Thread" object
		}
	}
}

Join chat

Adds an agent to chat.

Action RTM API Web API Push message
join_chat chat_users_updated

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats (joining by myself)
  • chats.meta--all:write - write access for meta data of all license chats
  • chats.meta--my:write - write access for meta data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes
agent_ids Yes

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"agent_ids": ["75a90b82-e6a4-4ded-b3eb-cb531741ee0d"]
}

No response payload.

Remove from chat

Removes users from chat. If no user is specified, it removes the current user. It’s forbidden to remove customer from chat.

Action RTM API Web API Push message
remove_from_chat chat_users_updated

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats (removing myself)
  • chats.conversation--my:write - write access for conversation data of chats requester belong to (removing myself)
  • chats.meta--all:write - write access for meta data of all license chats
  • chats.meta--my:write - write access for meta data of chats I belong to

Request payload

Request object Required Notes
chat_id Yes
agent_ids No

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"agent_ids": ["75a90b82-e6a4-4ded-b3eb-cb531741ee0d"]
}

No response payload.

Send event

Action RTM API Web API Push message
send_event incoming_event
or
incoming_chat_thread*

* incoming_chat_thread will be sent instead of incoming_event only if the event starts a new thread

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes Id of the chat that we want to send the message to
event Yes Event object

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"event": {
		"type": "message",
		"text": "hello world",
		"recipients": "agents",
		"custom_id": "12345-bhdsa"
	}
}

Sample response payload

{
	"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"event": {
		// "Event" object
	}
}

Send rich message postback

Action RTM API Web API Push message
send_rich_message_postback incoming_rich_message_postback*

* incoming_rich_message_postback will be sent only for active threads.

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes
thread_id Yes
event_id Yes
postback.id Yes Postback name of the button
postback.toggled Yes Postback toggled true/false

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
	"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
	"postback": {
		"id": "action_yes",
		"toggled": true
	}
}

No response payload.

Multicast

Action RTM API Web API Push message
multicast incoming_multicast

Permissions

  • multicast:write - access for multicast data to agents or customers

Request payload

Request object Required Notes
scopes Yes
content Yes JSON message to be sent
  • <scopes> can take the following values:
    • agents (object) can take the following values:
    • all (bool - include all agents)
    • ids ([]string - array of agent’s ids)
    • groups ([]string - array of group’s ids)
    • customers (object) can take the following values:
    • ids ([]string - array of customer’s ids)

At least one of scopes type (agents.all, agents.ids, agents.groups, customers.ids) is required.

Sample request payload

{
	"scopes": {
		"agents": {
			"all": true,
			"ids": ["john@gmail.com", "jane@gmail.com"],
			"groups": [1, 2]
		},
		"customers": {
			"ids": ["50ce4683-22a5-48bf-5317-340f40bf6dfe"]
		}
	},
	"content": {
		"example": {
			"nested": "json"
		}
	}
}

No response payload.

Send typing indicator

Action RTM API Web API Push message
send_typing_indicator -

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes Id of the chat that we want to send the typing indicator to
recipients No all (default), agents
is_typing Yes Bool

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"recipients": "all",
	"is_typing": true
}

No response payload.

Ban customer

Bans the customer for a specific period of time. It immediately disconnects all active sessions of this customer and does not accept new ones during the ban lifespan.

Action RTM API Web API Push message
ban_customer customer_banned

Permissions

  • customers.ban:write - access for banning customers

Request payload

Request object Required Notes
customer_id Yes
ban.days Yes

Sample request payload

{
	"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"ban": {
		"days": 5
	}
}

No response payload.

Close thread

Closes the thread. Nobody will be able to send any messages to this thread anymore.

Action RTM API Web API Push message
close_thread thread_closed

Permissions

  • chats.meta--all:write - write access for meta data of all license chats
  • chats.meta--my:write - write access for meta data of chats I belong to

Request payload

Request object Required Notes
chat_id Yes

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5"
}

No response payload.

Update chat scopes

Action RTM API Web API Push message
update_chat_scopes chat_scopes_updated

Permissions

  • chats.meta--all:write - write access for meta data of all license chats
  • chats.meta--my:write - write access for meta data of chats I belong to

Request payload

Request object Required Notes
chat_id Yes
add_scopes No Chat scopes to add
remove_scopes No Chat scopes to remove

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"add_scopes": {
		"groups": [1, 2]
	},
	"remove_scopes": {
		"groups": [3]
	}
}

No response payload.

Update agent

Updates agent properties.

Action RTM API Web API Push message
update_agent - agent_updated

Permissions

  • agents--my:write - write access for my profile configuration
  • agents--all:write - write access for all agents profiles configuration

Request payload

Request object Required Notes
agent_id No Current agent is used by default
routing_status No Possible values: accepting_chats, not_accepting_chats

Sample request payload

{
	"routing_status": "accepting_chats"
}

No response payload.

Change push notifications

Change firebase push notifications properties.

Action RTM API Web API Push message
change_push_notifications - -

No persmission is required to perform this action.

Request payload

Request object Required Notes
firebase_token Yes Firebase device token
platform Yes OS platform
enabled Yes Enable or disable push notifications for requested token
  • <platform> can take the following values:
    • ios - iOS operating system
    • android - Android operating system

Example request payload

{
	"firebase_token": "8daDAD9dada8ja1JADA11",
	"platform": "ios",
	"enabled": true
}

No response payload.

Update chat properties

Action RTM API Web API Push message
update_chat_properties chat_properties_updated

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes Id of the chat that we want to set property for
properties Yes Chat properties to set

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"properties": {
		"rating": {
			"score": 2,
			"comment": "Very good, veeeery good"
		},
		...
	}
}

No response payload.

Update chat thread properties

Action RTM API Web API Push message
update_chat_thread_properties chat_thread_properties_updated

Permissions

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats requester belong to

Request payload

Request object Required Notes
chat_id Yes Id of the chat that we want to set property for
thread_id Yes Id of the thread that we want to set property for
properties Yes Chat properties to set

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"thread_id": "EW2WQSA8",
	"properties": {
		"rating": {
			"score": 2,
			"comment": "Very good, veeeery good"
		},
		...
	}
}

No response payload.

Update last seen timestamp

Action RTM API Web API Push message
update_last_seen_timestamp last_seen_timestamp_updated

Permissions

  • chats--all:read - read access for all license chats
  • chats--my:read - read access for the chats requester belong to

Request payload

Request object Required Notes
chat_id Yes
timestamp No

Sample request payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"timestamp": 123456789
}

Sample response payload

{
	"timestamp": 123456789
}

Add auto chat scopes

Action RTM API Web API Push message
add_auto_chat_scopes - -

Permissions

  • auto_chat_scopes:write - write access for auto chat scopes configuration

Request payload

Request object Type Required Notes
scopes object Yes Destination scope
rules object Yes Rules to check for scope auto
description string No Auto chat scopes description
  • scopes object:

    {
    	"scopes": {
    		"groups": [1, 2]
    	}
    }
    
  • rules possible rules:

    • chat_properties.<namespace>.<name>.<filter_type>
    • <filter_type> can take the following values (only one is allowed for single property):
      • exists (bool)
      • values (type[] - array with specific type for property: string, int or bool)
      • exclude_values (type[] - array with specific type for property: string, int or bool)
    • customer_url.<string_filter_type>
    • <string_filter_type> can take the following values (only one is allowed for single customer_url):
      • values (match_object[])
      • exclude_values (match_object[])
    • <match_object> structure:
      • value - value to match (string)
      • exact_match - if exact match, if set to false a match_object.value will be matched as substring of customer_url

Sample request payload

{
	"description": "Chats from Facebook or Twitter",
	"scopes": {
		"groups": [1]
	},
	"rules": {
		"chat_properties": {
			"source": {
				"type": {
					"values": ["facebook", "twitter"]
				}
			},
			"facebook": {
				"page_id": {
					"values": ["63121487121"]
				}
			}
		},
		"customer_url": {
			"values": [{
				"value": "livechatinc.com",
				"exact_match": false
			}]
		}
	}
}

Sample response payload

{
	"auto_chat_scopes_id": "pqi8oasdjahuakndw9nsad9na"
}

Remove auto chat scopes

Action RTM API Web API Push message
remove_auto_chat_scopes - -

Permissions

  • auto_chat_scopes:write - write access for auto chat scopes configuration

Request payload

Request object Type Required Notes
auto_chat_scopes_id string Yes auto chat scopes ID

Sample request payload

{
	"auto_chat_scopes_id": "pqi8oasdjahuakndw9nsad9na"
}

No response payload.

Get auto chat scopes config

Action RTM API Web API Push message
get_auto_chat_scopes_config - -

Permissions

  • auto_chat_scopes:read - read access for auto chat scopes configuration

No request payload

Sample response payload

{
	"auto_chat_scopes_config": [{
		"id": "pqi8oasdjahuakndw9nsad9na",
		"description": "Chats from Facebook or Twitter",
		"scopes": {
			"groups": [1]
		},
		"rules": {
			"chat_properties": {
				"source": {
					"type": {
						"values": ["facebook", "twitter"]
					}
				},
				"facebook": {
					"page_id": {
						"values": ["63121487121"]
					}
				}
			},
			"customer_url": {
				"values": [{
					"value": "livechatinc.com",
					"exact_match": false
				}]
			}
		}
	}]
}

Upload image

Action RTM API Web API Push message
upload_image - -

No persmission is required to perform this action.

Request payload

Request object Required Notes
payload.image Yes max 10MB
  • Content-Type header in form Content-Type: multipart/form-data; boundary=<boundary> is required.

Sample request payload

	payload.image=test.png

Sample response payload

{
	"url": "https://cdn.chatio-static.com/api/file/chatio/img/24434343/dmkslfmndsfgds6fsdfsdnfsd.png",
	"path": "24434343/dmkslfmndsfgds6fsdfsdnfsd.png"
}

Notes:

  • url is a ready-to-use, temporary URL, but it can expire in the future
  • path should be used for database and must be appended to base_url
  • base_url is https://cdn.chatio-static.com/api/file/chatio/img

Pushes

Server => Client methods are used for keeping the application state up-to-date. They are available only in websocket transport.

Incoming chat thread

Action RTM API Webhook
incoming_chat_thread

Push payload

Object Notes
thread

Sample push payload

{
	"chat": {
		"id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
		"users": [
			// array of "User" objects
		],
		"properties": {
			"source": {
				"type": "facebook"
			},
			...
		},
		"thread": {
			// "Thread" object
		}
	}
}

Chat users updated

Action RTM API Webhook
chat_users_updated

Push payload

Object Notes
updated_users

Sample push payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"updated_users": {
		"customers": {
			"added": [
				// array of "User > Customer" objects
			],
			"removed_ids": []
		},
		"agents": {
			"added": [
				// array of "User > Agent" objects
			],
			"removed_ids": ["75a90b82-e6a4-4ded-b3eb-cb531741ee0d"]
		}
	}
}

Incoming event

Action RTM API Webhook
incoming_event

Push payload

Object Notes
chat_id
event

Sample push payload

{
	"chat_id": "85f3bfc9-06c1-434e-958b-2a5239b07de8",
	"event": {
		// "Event" object
	}
}

Incoming rich message postback

Action RTM API Webhook
incoming_rich_message_postback

Push payload

Object Notes
user_id
chat_id
thread_id
event_id
postback.id
postback.toggled

Sample push payload

{
	"user_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"thread_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
	"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
	"postback": {
		"id": "action_yes",
		"toggled": true
	}
}

Incoming multicast

Action RTM API Webhook
incoming_multicast -

Push payload

Object Notes
author_id
content

Sample push payload

{
	"author_id": "jack@gmail.com",
	"content": {
		"example": {
			"nested": "json"
		}
	}
}

Incoming typing indicator

Action RTM API Webhook
incoming_typing_indicator -

Push payload

Object Notes
chat_id
typing_indicator

Sample push payload

{
	"chat_id": "85f3bfc9-06c1-434e-958b-2a5239b07de8",
	"typing_indicator": {
		// "Typing indicator" object
	}
}

Incoming sneak peek

Action RTM API Webhook
incoming_sneak_peek -

Push payload

Object Notes
chat_id
sneak_peek

Sample push payload

{
	"chat_id": "85f3bfc9-06c1-434e-958b-2a5239b07de8",
	"sneak_peek": {
		// "Sneak peek" object
	}
}

Customer banned

Action RTM API Webhook
customer_banned -

Push payload

Object Notes
customer_id
ban.days

Sample push payload

{
	"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"ban": {
		"days": 5
	}
}

Thread closed

Action RTM API Webhook
thread_closed

Push payload

Object Notes
chat_id
thread_id
user_id Missing if thread was closed by router

Sample push payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"thread_id": "b0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
	"user_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d" // optional
}

Chat scopes updated

Action RTM API Webhook
chat_scopes_updated

Push payload

Object Notes
chat_id
scopes_added
scopes_removed

Sample push payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"scopes_added": {
		// "Scopes" object
	},
	"scopes_removed": {
		// "Scopes" object
	}
}

Customer updated

Action RTM API Webhook
customer_updated -

Push payload

Object Notes
chat_id
customer

Sample push payload

{
	"chat_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
	"customer": {
		// "User > Customer" object
	}
}

Agent updated

Action RTM API Webhook
agent_updated -

Push payload

Object Notes
agent_id
routing_status

Sample push payload

{
	"agent_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
	"routing_status": "accepting_chats"
}

Agent disconnected

Action RTM API Webhook
agent_disconnected -

Push payload

Object Notes
reason

Sample push payload

{
	"reason": "access_token_revoked"
}

Possible reasons

Type Notes
access_token_revoked Agent access token has been revoked
license_expired License has expired
agent_deleted Agent account has ben deleted
logged_out_remotely Agent has been logged out remotely
unsupported_version Connecting to unsupported version of Agent API

Chat properties updated

Action RTM API Webhook
chat_properties_updated

Push payload

Object Notes
chat_id
properties this is not a full properties object, this push shows only the properties which have been recently updated

Sample push payload

{
	"chat_id": "123-123-123-123",
	"properties": {
		"rating": {
			"score": {
				"value": 1
			},
			"comment": {
				"value": "Very good, veeeery good"
			}
		},
		...
	}
}

Chat thread properties updated

Action RTM API Webhook
chat_thread_properties_updated

Push payload

Object Notes
chat_id
thread_id
properties this is not a full properties object, this push shows only the properties which have been recently updated

Sample push payload

{
	"chat_id": "123-123-123-123",
	"thread_id": "E2WDHA8A",
	"properties": {
		"rating": {
			"value": {
				"value": 1
			},
			"comment": {
				"value": "Very good, veeeery good"
			}
		},
		...
	}
}

Last seen timestamp updated

Action RTM API Webhook
last_seen_timestamp_updated

Push payload

Object Notes
user_id
chat_id
timestamp

Sample push payload

{
	"user_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
	"chat_id": "123-123-123-123",
	"timestamp": 123456789
}