Configuration API
4 minutes reading time
Introduction
Configuration API is a service for storing configuration of license. You can set up here different types of features such as properties or webhooks.
Versioning
This document describes the Configuration API v3.1. This is the latest stable version recommended for the production use. Read more about versioning...
Authentication
Authentication for Configuration API is handled by access tokens. Find out how to get an access token from Agent authorization flows. If a method requires particular authorization scopes, you’ll find them included in the method description. Each request should contain the Authorization: Bearer <your_access_token> header.
Data centers
LiveChat system operates in two data centers: dal (USA) and fra (Europe). The default data center is dal.
All the LiveChat OAuth2.0 access tokens have a prefix: dal- or fra-. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.
Summing up, if the user token starts with fra-, you should add the X-Region: fra header. If the token starts with dal-, you don’t have to specify the header.
Propagation delay
All configurations set by this API will have action in system after max 2 minutes. This delay will be removed in the future.
Postman Collection
You can find all the requests from the Configuration API v3.1 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace the sample token with your own.
Bot Agents
Bot Agents enables writing integrations using the Agent Chat API - both RTM and Web - to communicate in chats as regular Agents.
A Bot Agent shares the SSO access token with the Agent who created the Bot. Each Bot Agent is a resource owned by an application in Developers Platform, identified by its own client_id.
Unlike Agents, Bot Agents don't have passwords or emails - you cannot log in as a Bot.
Methods
| HTTP method | The Bot Agents API endpoint |
|---|---|
POST | https://api.livechatinc.com/v3.1/configuration/action/<action> |
| Required header | Value | |
|---|---|---|
Content-Type | application/json |
Create Bot Agent
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/create_bot_agent |
| Required scopes | agents-bot--my:rw |
Request
| Request object | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | Display name |
status * | string | Yes | Agent status |
avatar | string | No | Avatar URL |
max_chats_count | int | No | Max. number of incoming chats that can be routed to an Agent; default: 6. |
default_group_priority *** | string | No | The default routing priority for a group without defined priority. |
groups | object[] | No | Groups an Agent belongs to. |
groups[].id | uint | Yes | Group ID; required only when group's included. |
groups[].priority ** | string | Yes | Agent's priority in a group; required only when group's included. |
webhooks | object | No | Webhooks sent to the Agent; for more info on possible values and payload, see Webhooks. Webhooks work only for online Bots. |
webhooks.url | string | Yes | Destination URL for webhooks; required only when webhooks is included. |
webhooks.secret_key | string | Yes | Secret sent in webhooks to verify webhook's source; required only when webhooks's included. |
webhooks.actions | object[] | Yes | Triggering actions; required only when webhooks's included. |
webhooks.actions[].name | string | Yes | The name of the triggering action; required only when webhooks is included. |
webhooks.actions[].filters | object | No | Filters to check if a webhook should be triggered. For more info on filters, see Register webhook. |
webhooks.actions[].additional_data | string[] | No | Additional data that will arrive with webhooks. |
* The table below presents the possible values for the status parameter:
| Possible value | Notes |
|---|---|
accepting chats | Agent is logged in. The chat router routes incoming chats to the Agent. |
not accepting chats | Agent is logged in, but the chat router doesn't route incoming chats to the Agent. |
offline | Agent isn't logged in. |
** The table below presents the possible values for the groups[].priority parameter:
| Possible value | Notes |
|---|---|
first | The highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. |
normal | The medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. |
last | The lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. |
*** The table below presents the possible values for the default_group_priority parameter:
| Possible values | Notes |
|---|---|
first | The highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. |
normal | The medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. |
last | The lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. |
supervisor | Bot works as supervisor so it will not be assigned to any chats. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/create_bot_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Bot Name",
"status": "accepting chats"
}'Response
Copied!
{
"bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}Remove Bot Agent
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/remove_bot_agent |
| Required scopes | agents-bot--my:rw agents-bot--all:rw |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
bot_agent_id | Yes | string | Bot Agent ID |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/remove_bot_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"bot_agent_id": "505591fc9fc2d6e92798bed7d9d8f079"
}'Update Bot Agent
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/update_bot_agent |
| Required scopes | agents-bot--my:rw |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
id | Yes | string | Bot Agent ID |
name | No | string | Display name |
avatar | No | string | Avatar URL |
status * | No | string | Agent status |
max_chats_count | No | int | Maximum incoming chats that can be routed to an Agent. |
groups | No | object[] | Groups an Agent belongs to |
groups[].id | Yes | uint | Group ID, required only when groups's present. |
groups[].priority ** | Yes | string | Agent's priority in the group; required only when groups is included. |
default_group_priority *** | No | string | The default routing priority for a group without defined priority. |
webhooks | No | object | Webhooks sent to an Agent. Webhooks work only for online Bots. |
webhooks.url | Yes | string | Destination URL for webhooks; required only when webhooks is present. |
webhooks.secret_key | Yes | string | Secret sent in webhooks to verify the webhook's source; required when webhooks is included. |
webhooks.actions | Yes | object[] | Triggering actions; required only when webhooks is included. |
webhooks.actions[].name | Yes | string | The name of the triggering action; required only when webhooks is included. |
webhooks.actions[].filters | No | object | Filters to check if a webhook should be triggered. For more info on filters, see Register webhook. |
webhooks.actions[].additional_data | No | string[] | Additional data arriving with the webhook. |
* The table below presents the possible values for the status parameter:
| Possible values | Notes |
|---|---|
accepting chats | Agent is logged in. The chat router routes incoming chats to the Agent. |
not accepting chats | Agent is logged in, but the chat router doesn't route incoming chats to the Agent. |
offline | Agent isn't logged in. |
** The table below presents the possible values for the groups[].priority parameter:
| Possible values | Notes: |
|---|---|
first | The highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. |
normal | The medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. |
last | The lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. |
*** The table below presents the possible values for the default_group_priority parameter:
| Possible values | Notes |
|---|---|
first | The highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. |
normal | The medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. |
last | The lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. |
supervisor | Bot works as supervisor so it will not be assigned to any chats. |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/update_bot_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "ce54714e3d2b53adbfff09dbdbdd56e9",
"name": "New Bot Name"
}'Get Bot Agents
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/get_bot_agents |
| Required scopes | agents-bot--my:ro agents-bot--all:ro |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
all | No | bool | Get all Bot Agents, if false returns only caller's Bot Agents, default value is false |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/get_bot_agents \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"all": false
}'Response
Copied!
{
"bot_agents": [{
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "John Doe",
"avatar": "https://example.com/avatar.jpg",
"status": "accepting chats"
}]
}Get Bot Agent Details
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/get_bot_agent_details |
| Required scopes | agents-bot--my:ro agents-bot--all:ro |
Request
| Parameter | Required | Type | Notes |
|---|---|---|---|
bot_agent_id | Yes | string | Bot Agent ID |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/get_bot_agent_details \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}'Response
Copied!
{
"bot_agent": {
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "John Doe",
"avatar": "https://example.com/avatar.jpg",
"status": "accepting chats",
"application": {
"client_id": "asXdesldiAJSq9padj"
},
"max_chats_count": 6,
"groups": [{
"id": 0,
"priority": "normal"
}, {
"id": 1,
"priority": "normal"
}, {
"id": 2,
"priority": "first"
}],
"webhooks": {
"url": "http://myservice.com/webhooks",
"secret_key": "JSauw0Aks8l-asAa",
"actions": [{
"name": "incoming_chat_thread",
"filters": {
"chat_properties": {
"source": {
"type": {
"values": ["facebook", "twitter"]
}
}
}
}
},{
"name": "incoming_event",
"additional_data": ["chat_properties"]
}]
}
}
}Properties
Properties are key-value storages. They can be set within a chat, a thread, or an event.
You can create properties within a license and configure them using the Configuration API. Properties are grouped in namespaces, which helps distinguishing which property belongs to a given integration. Your namespace is always named after your Client Id.
You can configure the property type, location, and domain.
Property types
There are four property types:
int(int32)boolstringtokenized_string
The tokenized_string type is a string split to tokens before indexing in our search engine. It can be useful for longer strings, such as messages. It should not be used for keywords.
Property locations
Properties can be set for the following locations:
- chat
- thread
- event
You can configure access to properties within those locations. For example, you could create a property visible only to agents in a chat and thread, but not in an event.
Property domain
The property domain is a set of values that a property can be assigned to.
Property domain can be configured in two ways:
- by defining a set of values explicitly allowed in this property (for example
[1, 2, 3]). - by defining a range. All values within the range are allowed in this property. It works only for numeric types (for example a range from
1to3).
Test properties
Each license has some test properties that you can use to play with properties.
| Namespace | Property | Type | Access |
|---|---|---|---|
test | bool_property | bool | rw for everyone everywhere |
test | int_property | int | rw for everyone everywhere |
test | string_property | string | rw for everyone everywhere |
test | tokenized_string_property | tokenized_string | rw for everyone everywhere |
The tokenized_string property is similar to the string type. The values of a tokenized_string are split in tokens to enable searching for each word separately.
The general properties formatCopied!
{
"properties": {
"<namespace>": {
"<property_name>": "<property_value>",
"<property_name>": "<property_value>"
}
}
}Methods
| HTTP method | The Properties API endpoint |
|---|---|
POST | https://api.livechatinc.com/v3.1/configuration/action/<action> |
| Required header | Value | |
|---|---|---|
Content-Type | application/json |
Create Properties
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/create_properties |
| Required scopes | properties--my:rw(to create my properties in my namespace) |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
<property_name>.type | Yes | string | Possible values: int, string, bool, and tokenized_string |
<property_name>.locations | Yes | object | |
<property_name>.locations.<location> | min. one location | object | Possible values: chat, thread, event |
<property_name>.locations.<location>.access.<user> | min. one user | object | Possible values: agent, customer |
<property_name>.locations.<location>.access.<user>.read | Yes | bool | If set to true, then <user> can read this property. |
<property_name>.locations.<location>.access.<user>.write | Yes | bool | If set to true, then <user> can write to this property. |
<property_name>.description | No | string | Property description |
<property_name>.domain * | No | [<type>] | Array of values that properties can be set to. |
<property_name>.range * | No | object | Range of values that properties can be set to. |
<property_name>.range.from | No | int | Only values equal or greater than this parameter can be set to this property. |
<property_name>.range.to | No | int | Only values equal or lower than this parameter can be set to this property. |
*) Only one domain and one range can be set for a single property.
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/create_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"score": {
"type": "int",
"locations": {
"chat": {
"access": {
"agent": {
"read": true,
"write": true
},
"customer": {
"read": true,
"write": true
}
}
}
}
},
"comment": {
"type": "string",
"locations": {
"chat": {
"access": {
"agent": {
"read": true,
"write": true
},
"customer": {
"read": true,
"write": true
}
}
}
}
}
}'Get Property Configs
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/get_property_configs |
| Required scopes | properties--my:ro properties--all:ro (to create properties in all namespaces) |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
all | No | bool | If set to true, it returns all properties within a given license; default: false. |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/get_property_configs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'Response
Copied!
{
"58737b5829e65621a45d598aa6f2ed8e":{
"greeting":{
"type":"string",
"locations":{
"chat":{
"access":{
"agent":{
"read":true,
"write":false
},
"customer":{
"read":true,
"write":true
}
}
}
},
"domain": ["hello", "hi"]
},
"scoring":{
"type":"int",
"locations":{
"event":{
"access":{
"agent":{
"read":true,
"write":true
}
}
}
},
"range": {
"from": 0,
"to": 10
}
}
}
}Webhooks
Here's what you need to know about webhooks:
- Webhooks notify you when specific events occur.
- They can be generated by both Web and RTM API actions.
- To receive webhooks, you need to register them first.
When your server receives a webhook from LiveChat, it should respond with HTTP 200 response. Otherwise, LiveChat will retry sending the webhook to your service a number of times until it receives the correct HTTP 200 response.
The timeout is set to ~10 seconds. If we don't receive HTTP 200 response within that time period, we'll retry sending the webhook up to 10 times within 6 hours.
Available webhooks:
general webhook format
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "<action>",
"payload": {
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Chats
incoming_chat_thread
Informs about a new thread coming in the chat. The webhook payload contains not only the new thread, but the whole chat data structure. If the chat was started with some initial events, the thread object contains them.
Specifics
| Action | incoming_chat_thread |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
chat | Chat data structure |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_chat_thread",
"payload": {
"chat": {
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"properties": {
"source": {
"type": "facebook"
},
...
},
"thread": {
// "Thread" object
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}thread_closed
Informs that a thread was closed.
Specifics
| Action | thread_closed |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
user_id | Missing if a thread was closed by the router. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_closed",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Chat access
access_granted
Informs that new, single access to a resource was granted. The existing access isn't overwritten.
Specifics
| Action | access_granted |
| Push equivalent in | Agent Chat API |
Webhook payload
| Object | Notes |
|---|---|
access | The entities that were granted access to the specified resource |
resource | Resource type |
id | Resource id |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "access_granted",
"payload": {
"resource": "chat",
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1] // Agents from group 1 were granted access to the chat with id PJ0MRSHTDG
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}access_revoked
Informs that access to a certain resource was revoked.
Specifics
| Action | access_revoked |
| Push equivalent in | Agent Chat API |
Webhook payload
| Object | Notes |
|---|---|
access | The entities that lost access to the specified resource |
resource | Resource type |
id | Resource Id |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "access_revoked",
"payload": {
"resource": "chat",
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1] // Agents from group 1 lost access to the chat with id PJ0MRSHTDG
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}access_set
Informs that new, single access to a resource was set. The existing access is overwritten.
Specifics
| Action | access_set |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
access | The entities that were given access to the specified resource |
resource | Resource type |
id | Resource id |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "access_set",
"payload": {
"resource": "chat",
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1] // Agents from group 1 were granted given to the chat with id PJ0MRSHTDG
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Chat users
chat_user_added
Informs that a user (Customer or Agent) was added to a chat.
Specifics
| Action | chat_user_added |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
user_type | Possible values: agent, customer |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_user_added",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user": {
// "User > Customer" or "User > Agent" object
},
"user_type": "agent"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}chat_user_removed
Informs that a user (Customer or Agent) was removed from a chat.
Specifics
| Action | chat_user_removed |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
user_type | Possible values: agent, customer |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_user_removed",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "agent1@example.com",
"user_type": "agent"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Events
incoming_event
Informs about an incoming event sent to a chat.
Specifics
| Action | incoming_event |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_event",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event": {
// "Event" object
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}event_updated
Informs that an event was updated.
Specifics
| Action | event_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_updated",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event": {
// "Event" object
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}incoming_rich_message_postback
Informs about an incoming rich message postback. The webhook payload contains the info on the postback itself, as well as the chat it was sent in.
Specifics
| Action | incoming_rich_message_postback |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_rich_message_postback",
"payload": {
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"postback": {
"id": "action_yes",
"toggled": true
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Properties
chat_properties_updated
Informs about those chat properties that were updated.
Specifics
| Action | chat_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_updated",
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": {
"score": 1,
"comment": "Very good, very good"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}chat_properties_deleted
Informs about those chat properties that were deleted.
Specifics
| Action | chat_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_deleted",
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": ["score", "comment"]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}chat_thread_properties_updated
Informs about those chat thread properties that were updated.
Specifics
| Action | chat_thread_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_thread_properties_updated",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": {
"score": 1,
"comment": "Very good, very good"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}chat_thread_properties_deleted
Informs about those chat thread properties that were deleted.
Specifics
| Action | chat_thread_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_thread_properties_deleted",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": ["score", "comment"]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}event_properties_updated
Informs about those event properties that were updated.
Specifics
| Action | event_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | This is not a full properties object. This webhook shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_updated",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"rating": {
"score": 1,
"comment": "Very good, very good"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}event_properties_deleted
Informs about those event properties that were deleted.
Specifics
| Action | event_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Object | Notes |
|---|---|
properties | This is not a full properties object. This webhook shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_deleted",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"rating": ["score", "comment"]
},
// ...
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Thread tags
chat_thread_tagged
Informs that a chat thread was tagged.
Specifics
| Action | chat_thread_tagged |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_thread_tagged",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}chat_thread_untagged
Informs that a chat thread was untagged.
Specifics
| Action | chat_thread_untagged |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_thread_untagged",
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Status
agent_status_changed
Informs that an Agent's status changed.
Specifics
| Action | agent_status_changed |
| Push equivalent in | Agent Chat API |
Webhook payload
| Object | Notes |
|---|---|
status | Possible values: accepting chats, not accepting chats, offline |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "agent_status_changed",
"payload": {
"agent_id":"agent1@example.com",
"status": "accepting chats"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}agent_deleted
Informs that an Agent's account was deleted.
Specifics
| Action | agent_deleted |
| Push equivalent in | - |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "agent_deleted",
"payload": {
"agent_id": "agent1@example.com"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Customers
customer_created
Informs that a new Customer registered.
Specifics
| Action | customer_created |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "customer_created",
"payload": {
// "User > Customer" object
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"created_at": "2019-11-14T14:27:24.410018Z",
"email": "customer1@example.com",
"avatar": "https://example.com/avatars/1.jpg",
"fields": {
"some_key": "some_value"
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Other
events_marked_as_seen
Informs that a user has seen events up to a specific time.
Specifics
| Action | events_marked_as_seen |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "events_marked_as_seen",
"payload": {
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}Methods
| HTTP method | The Webhooks API endpoint |
|---|---|
POST | https://api.livechatinc.com/v3.1/configuration/action/<action> |
| Required header | Value | |
|---|---|---|
Content-Type | application/json |
Register Webhook
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/register_webhook |
| Required scopes | webhooks--my:rw |
| Request object | Required | Data type | Notes |
|---|---|---|---|
action* | Yes | string | The action that triggers sending a webhook. |
secret_key | Yes | string | The secret key sent in webhooks to verify the source of a webhook. |
url | Yes | string | Destination URL for the webhook |
additional_data** | No | []string | Additional data that will arrive with the webhook. |
description | No | string | Webhook description |
filters | No | object | Filters to check if a webhook should be triggered. |
filters.author_type | No | string | Possible values: customer, agent; allowed only for incoming_event and event_updated actions. |
filters.only_my_chats | No | bool | true or false; triggers webhooks only for chats with the property source.client_id set to my client_id. |
filters.chat_member_ids | No | object | Only one filter (agents_any or agents_exclude) is allowed. |
filters.chat_member_ids.agents_any | No | []string | Array of Agents' ids; if any specified Agent is in the chat, the webhook will be triggered. |
filters.chat_member_ids.agents_exclude | No | []string | Array of Agents' ids; If any specified Agent is in the chat, the webhook will not be triggered. |
Triggering actions
* The table below presents the possible values for the action parameter.
| Possible action | Informs about | Available filters |
|---|---|---|
incoming_chat_thread | incoming_chat_thread | chat_member_ids, only_my_chats |
incoming_event | incoming_event | chat_member_ids, author_type, only_my_chats |
event_updated | event_updated | chat_member_ids, author_type, only_my_chats |
incoming_rich_message_postback | incoming_rich_message_postback | chat_member_ids, only_my_chats |
last_seen_timestamp_updated | last_seen_timestamp_updated | chat_member_ids, only_my_chats |
thread_closed | thread_closed | chat_member_ids, only_my_chats |
chat_properties_updated | chat_properties_updated | chat_member_ids, only_my_chats |
chat_properties_deleted | chat_properties_deleted | chat_member_ids, only_my_chats |
chat_thread_properties_updated | chat_thread_properties_updated | chat_member_ids, only_my_chats |
chat_thread_properties_deleted | chat_thread_properties_deleted | chat_member_ids, only_my_chats |
chat_user_added | chat_user_added | chat_member_ids, only_my_chats |
chat_user_removed | chat_user_removed | chat_member_ids, only_my_chats |
chat_thread_tagged | chat_thread_tagged | chat_member_ids, only_my_chats |
chat_thread_untagged | chat_thread_untagged | chat_member_ids, only_my_chats |
agent_status_changed | agent_updated | chat_member_ids |
agent_deleted | An Agent's account being deleted from the license | chat_member_ids |
* The table below presents the possible values for the additional_data parameter:
| Possible value | Available for actions |
|---|---|
access | incoming_event, chat_user_added |
chat_properties | All actions, except for agent_status_changed and agent_deleted |
thread_id | chat_user_added |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/register_webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"url": "http://myservice.com/webhooks",
"description": "Test webhook",
"action": "thread_closed",
"secret_key": "laudla991lamda0pnoaa0"
}'Response
Copied!
{
"webhook_id": "pqi8oasdjahuakndw9nsad9na"
}Get Webhooks Config
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/get_webhooks_config |
| Required scopes | webhooks--my:rw webhooks--all:ro |
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/get_webhooks_config \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'Response
Copied!
[
{
"webhook_id": "pqi8oasdjahuakndw9nsad9na",
"url": "http://myservice.com/webhooks",
"description": "Test webhook",
"action": "thread_closed",
"filters": {
"chat_member_ids": {
"agents_any": ["johndoe@mail.com"]
}
},
"owner_client_id": "asXdesldiAJSq9padj"
}
]Unregister Webhook
Specifics
| Method URL | https://api.livechatinc.com/v3.1/configuration/action/unregister_webhook |
| Required scopes | webhooks--my:rw webhooks--all:rw |
Request
| Parameter | Required | Data type | Notes |
|---|---|---|---|
webhook_id | Yes | string | Webhook ID |
Response
No response payload (200 OK).
REQUESTCopied!
curl -X POST \
https://api.livechatinc.com/v3.1/configuration/action/unregister_webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"webhook_id": "pqi8oasdjahuakndw9nsad9na"
}'Contact us
If you found a bug or a typo, you can let us know directly on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@livechatinc.com. We'll be happy to hear from you!