API version

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 versionig...

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.

Run in Postman

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 methodThe Bot Agents API endpoint
POSThttps://api.livechatinc.com/v3.1/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Create Bot Agent

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/create_bot_agent
Required scopesagents-bot--my:rw
Request
Request objectTypeRequiredNotes
namestringYesDisplay name
status *stringYesAgent status
avatarstringNoAvatar URL
max_chats_countintNoMax. number of incoming chats that can be routed to an Agent; default: 6.
default_group_priority ***stringNoThe default routing priority for a group without defined priority.
groupsobject[]NoGroups an Agent belongs to.
groups[].iduintYesGroup ID; required only when group's included.
groups[].priority **stringYesAgent's priority in a group; required only when group's included.
webhooksobjectNoWebhooks sent to the Agent; for more info on possible values and payload, see Webhooks.
webhooks.urlstringYesDestination URL for webhooks; required only when webhooks is included.
webhooks.secret_keystringYesSecret sent in webhooks to verify webhook's source; required only when webhooks's included.
webhooks.actionsobject[]YesTriggering actions; required only when webhooks's included.
webhooks.actions[].namestringYesThe name of the triggering action; required only when webhooks is included.
webhooks.actions[].filtersobjectNoFilters to check if a webhook should be triggered. For more info on filters, see Register webhook.
webhooks.actions[].additional_datastring[]NoAdditional data that will arrive with webhooks.

* The table below presents the possible values for the status parameter:

Possible valueNotes
accepting chatsAgent is logged in. The chat router routes incoming chats to the Agent.
not accepting chatsAgent is logged in, but the chat router doesn't route incoming chats to the Agent.
offlineAgent isn't logged in.

** The table below presents the possible values for the groups[].priority parameter:

Possible valueNotes
firstThe 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.
normalThe 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.
lastThe 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 valuesNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBot works as supervisor so it will not be assigned to any chats.
REQUEST
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
{
    "bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}

Remove Bot Agent

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/remove_bot_agent
Required scopesagents-bot--my:rw agents-bot--all:rw
Request
ParameterRequiredTypeNotes
bot_agent_idYesstringBot Agent ID
Response

No response payload (200 OK).

REQUEST
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 URLhttps://api.livechatinc.com/v3.1/configuration/action/update_bot_agent
Required scopesagents-bot--my:rw
Request
ParameterRequiredData typeNotes
idYesstringBot Agent ID
nameNostringDisplay name
avatarNostringAvatar URL
status *NostringAgent status
max_chats_countNointMaximum incoming chats that can be routed to an Agent.
groupsNoobject[]Groups an Agent belongs to
groups[].idYesuintGroup ID, required only when groups's present.
groups[].priority **YesstringAgent's priority in the group; required only when groups is included.
default_group_priority ***NostringThe default routing priority for a group without defined priority.
webhooksNoobjectWebhooks sent to an Agent
webhooks.urlYesstringDestination URL for webhooks; required only when webhooks is present.
webhooks.secret_keyYesstringSecret sent in webhooks to verify the webhook's source; required when webhooks is included.
webhooks.actionsYesobject[]Triggering actions; required only when webhooks is included.
webhooks.actions[].nameYesstringThe name of the triggering action; required only when webhooks is included.
webhooks.actions[].filtersNoobjectFilters to check if a webhook should be triggered. For more info on filters, see Register webhook.
webhooks.actions[].additional_dataNostring[]Additional data arriving with the webhook.

* The table below presents the possible values for the status parameter:

Possible valuesNotes
accepting chatsAgent is logged in. The chat router routes incoming chats to the Agent.
not accepting chatsAgent is logged in, but the chat router doesn't route incoming chats to the Agent.
offlineAgent isn't logged in.

** The table below presents the possible values for the groups[].priority parameter:

Possible valuesNotes:
firstThe 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.
normalThe 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.
lastThe 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 valuesNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBot works as supervisor so it will not be assigned to any chats.
Response

No response payload (200 OK).

REQUEST
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 URLhttps://api.livechatinc.com/v3.1/configuration/action/get_bot_agents
Required scopesagents-bot--my:ro agents-bot--all:ro
Request
ParameterRequiredTypeNotes
allNoboolGet all Bot Agents, if false returns only caller's Bot Agents, default value is false
REQUEST
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
{
    "bot_agents": [{
        "id": "5c9871d5372c824cbf22d860a707a578",
        "name": "John Doe",
        "avatar": "https://example.com/avatar.jpg",
        "status": "accepting chats"
    }]
}

Get Bot Agent Details

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/get_bot_agent_details
Required scopesagents-bot--my:ro agents-bot--all:ro
Request
ParameterRequiredTypeNotes
bot_agent_idYesstringBot Agent ID
REQUEST
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
{
    "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)
  • bool
  • string
  • tokenized_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 1 to 3).

Test properties

Each license has some test properties that you can use to play with properties.

NamespacePropertyTypeAccess
testbool_propertyboolrw for everyone everywhere
testint_propertyintrw for everyone everywhere
teststring_propertystringrw for everyone everywhere
testtokenized_string_propertytokenized_stringrw 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 format
{
    "properties": {
        "<namespace>": {    
            "<property_name>": "<property_value>",    
            "<property_name>": "<property_value>"      
        }
    }
}

Methods

HTTP methodThe Properties API endpoint
POSThttps://api.livechatinc.com/v3.1/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Create Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/create_properties
Required scopesproperties--my:rw(to create my properties in my namespace)
Request
ParameterRequiredData typeNotes
<property_name>.typeYesstringPossible values: int, string, bool, and tokenized_string
<property_name>.locationsYesobject
<property_name>.locations.<location>min. one locationobjectPossible values: chat, thread, event
<property_name>.locations.<location>.access.<user>min. one userobjectPossible values: agent, customer
<property_name>.locations.<location>.access.<user>.readYesboolIf set to true, then <user> can read this property.
<property_name>.locations.<location>.access.<user>.writeYesboolIf set to true, then <user> can write to this property.
<property_name>.descriptionNostringProperty description
<property_name>.domain *No[<type>]Array of values that properties can be set to.
<property_name>.range *NoobjectRange of values that properties can be set to.
<property_name>.range.fromNointOnly values equal or greater than this parameter can be set to this property.
<property_name>.range.toNointOnly 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).

REQUEST
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 URLhttps://api.livechatinc.com/v3.1/configuration/action/get_property_configs
Required scopesproperties--my:ro properties--all:ro (to create properties in all namespaces)
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, it returns all properties within a given license; default: false.
REQUEST
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
{
    "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:
Chatsincoming_chat_thread thread_closed
Chat accessaccess_granted access_revoked access_set
Chat userschat_user_added chat_user_removed
Eventsincoming_event event_updated incoming_rich_message_postback
Propertieschat_properties_updated chat_properties_deleted chat_thread_properties_deleted chat_thread_properties_updated event_properties_updated event_properties_deleted
Thread tagschat_thread_tagged chat_thread_untagged
Statusagent_status_changed agent_deleted
Customerscustomer_created
Otherevents_marked_as_seen
general webhook format
{
  "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
Actionincoming_chat_thread
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
chatChat data structure
Sample webhook
{
  "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
Actionthread_closed
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_idMissing if a thread was closed by the router.
Sample webhook
{
  "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
Actionaccess_granted
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
accessThe entities that were granted access to the specified resource
resourceResource type
idResource id
Sample webhook
{
  "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
Actionaccess_revoked
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
accessThe entities that lost access to the specified resource
resourceResource type
idResource Id
Sample webhook
{
  "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
Actionaccess_set
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
accessThe entities that were given access to the specified resource
resourceResource type
idResource id
Sample webhook
{
  "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
Actionchat_user_added
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_typePossible values: agent, customer
Sample webhook
{
  "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
Actionchat_user_removed
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_typePossible values: agent, customer
Sample webhook
{
  "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
Actionincoming_event
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
{
  "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
Actionevent_updated
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
{
  "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
Actionincoming_rich_message_postback
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
{
  "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
Actionchat_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionchat_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionchat_thread_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionchat_thread_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionevent_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesThis is not a full properties object. This webhook shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionevent_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesThis is not a full properties object. This webhook shows only the properties that have been recently updated.
Sample webhook
{
  "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
Actionchat_thread_tagged
Push equivalent inAgent Chat API
Sample webhook
{
  "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
Actionchat_thread_untagged
Push equivalent inAgent Chat API
Sample webhook
{
  "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
Actionagent_status_changed
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
statusPossible values: accepting chats, not accepting chats, offline
Sample webhook
{
  "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
Actionagent_deleted
Push equivalent inAgent Chat API
Sample webhook
{
  "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
Actioncustomer_created
Push equivalent inAgent Chat API
Sample webhook
{
  "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
Actionevents_marked_as_seen
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
{
  "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 methodThe Webhooks API endpoint
POSThttps://api.livechatinc.com/v3.1/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Register Webhook

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/register_webhook
Required scopeswebhooks--my:rw
Request objectRequiredData typeNotes
action*YesstringThe action that triggers sending a webhook.
secret_keyYesstringThe secret key sent in webhooks to verify the source of a webhook.
urlYesstringDestination URL for the webhook
additional_data**No[]stringAdditional data that will arrive with the webhook.
descriptionNostringWebhook description
filtersNoobjectFilters to check if a webhook should be triggered.
filters.author_typeNostringPossible values: customer, agent; allowed only for incoming_event and event_updated actions.
filters.only_my_chatsNobooltrue or false; triggers webhooks only for chats with the property source.client_id set to my client_id.
filters.chat_member_idsNoobjectOnly one filter (agents_any or agents_exclude) is allowed.
filters.chat_member_ids.agents_anyNo[]stringArray of Agents' ids; if any specified Agent is in the chat, the webhook will be triggered.
filters.chat_member_ids.agents_excludeNo[]stringArray 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 actionInforms aboutAvailable filters
incoming_chat_threadincoming_chat_threadchat_member_ids, only_my_chats
incoming_eventincoming_eventchat_member_ids, author_type, only_my_chats
event_updatedevent_updatedchat_member_ids, author_type, only_my_chats
incoming_rich_message_postbackincoming_rich_message_postbackchat_member_ids, only_my_chats
last_seen_timestamp_updatedlast_seen_timestamp_updatedchat_member_ids, only_my_chats
thread_closedthread_closedchat_member_ids, only_my_chats
chat_properties_updatedchat_properties_updatedchat_member_ids, only_my_chats
chat_properties_deletedchat_properties_deletedchat_member_ids, only_my_chats
chat_thread_properties_updatedchat_thread_properties_updatedchat_member_ids, only_my_chats
chat_thread_properties_deletedchat_thread_properties_deletedchat_member_ids, only_my_chats
chat_user_addedchat_user_addedchat_member_ids, only_my_chats
chat_user_removedchat_user_removedchat_member_ids, only_my_chats
chat_thread_taggedchat_thread_taggedchat_member_ids, only_my_chats
chat_thread_untaggedchat_thread_untaggedchat_member_ids, only_my_chats
agent_status_changedagent_updatedchat_member_ids
agent_deletedAn Agent's account being deleted from the licensechat_member_ids

* The table below presents the possible values for the additional_data parameter:

Possible valueAvailable for actions
accessincoming_event, chat_user_added
chat_propertiesAll actions, except for agent_status_changed and agent_deleted
thread_idchat_user_added
REQUEST
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
{
  "webhook_id": "pqi8oasdjahuakndw9nsad9na"
}

Get Webhooks Config

Specifics
Method URLhttps://api.livechatinc.com/v3.1/configuration/action/get_webhooks_config
Required scopeswebhooks--my:rw webhooks--all:ro
REQUEST
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
[
    {
      "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 URLhttps://api.livechatinc.com/v3.1/configuration/action/unregister_webhook
Required scopeswebhooks--my:rw webhooks--all:rw
Request
ParameterRequiredData typeNotes
webhook_idYesstringWebhook ID
Response

No response payload (200 OK).

REQUEST
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!