Configuration API
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.2. 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.2 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.
Agents
An Agent is a type of user who communicates with Customers. The Agent data structure consists of several fields, which you can look up here. The requester can view and modify some of the fields, but others are read-only.
Methods
HTTP method | The Agents API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.2/configuration/action/<action> |
Required header | Value |
---|---|
Content-Type | application/json |
Create Agent
Creates a new Agent with specified parameters within a license. If the requester has the billing:rw
scope, then the newly created Agent will have the awaiting_approval
property marked as false
by default; otherwise it'll be true
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/create_agent |
Required scopes | accounts--all:rc |
Request
Parameter | Data type | Required | Notes |
---|---|---|---|
id | string | Yes | Agent ID |
name | string | Yes | Agent name |
role | string | No | Agent role, should be one of the following: viceowner , administrator , normal (default). |
avatar_path | string | No | URL path of the Agent's avatar |
job_title | string | No | Agent's job title |
mobile | string | No | Agent's mobile number |
max_chats_count | int | No | Agent's maximum number of concurrent chats |
awaiting_approval | bool | No | Determines if the Agent will be awaiting approval after creation. Only a requester with the billing:rw scope can set this value to false . |
groups | object[] | No | Groups an Agent belongs to. |
groups[].id | uint | Yes | Group ID; required only when group is included. |
groups[].priority * | string | Yes | Agent's priority in a group; required only when group is included. |
notifications ** | string[] | No | Represents which Agent notifications are turned on. |
email_subscriptions *** | string[] | No | Represents which subscriptions will be send to the Agent via email. |
work_scheduler | object | No | Work scheduler options to set for the new Agent |
work_scheduler.****.<work_scheduler> | object | No | <work_scheduler> values ***** |
* 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. Corresponds to the Primary priority option in the LiveChat App. |
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. Corresponds to the Secondary priority option in the LiveChat App. |
** Possible values for the notifications
array:
new_visitor
incoming_chat
returning_visitor
queued_visitor
visitor_is_typing
new_goal
unassigned_chats
unassigned_chat_messages
ticket
inactive_notifications
mute_all_sounds
repeat_sound_notifications
ticket_notifications
*** Possible values for the email_subscriptions
array:
daily_summary
weekly_summary
**** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
***** <work_scheduler>
contains the following fields:
start
(string
) - the time when the Agent starts work, in the format:HH:MM
end
(string
) - the time when the Agent finishes work, in the format:HH:MM
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/create_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com",
"name": "Agent Smith",
"role": "viceowner",
"groups": [
{
"id": 5,
"priority": "first"
},
{
"id": 2,
"priority": "last"
},
{
"id": 1,
"priority": "normal"
}
],
"work_scheduler": {
"monday": {
"start": "08:30",
"end": "12:30"
}
},
"notifications": [
"new_visitor",
"new_goal",
"visitor_is_typing"
],
"email_subscriptions": [
"weekly_summary"
]
}'
{
"id": "smith@example.com"
}
Get Agent
It returns the info about an Agent specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/get_agent |
Required scopes | agents--my:ro agents--all:ro |
Request
Request object | Type | Required | Notes |
---|---|---|---|
id | string | Yes | Agent ID |
fields * | string[] | No | Additional fields to include. |
* Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
work_scheduler | Work scheduler object for an Agent |
groups | Groups an Agent belongs to |
email_subscriptions | A list of an Agent's active subscriptions |
notifications | A list of an Agent's enabled notifications |
job_title | Agent's job title |
mobile | Agent's mobile number |
max_chats_count | Agent's maximum number of concurrent chats |
suspended | Boolean value indicating if an Agent is suspended |
awaiting_approval | Boolean value indicating if an Agent is awaiting approval |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/get_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
{
"id": "smith@example.com",
"name": "Agent Smith",
"avatar_path": "https://domain.com/avatar.image.jpg",
"role": "administrator",
"login_status": "accepting chats"
}
List Agents
Returns all Agents within a license.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_agents |
Required scopes | agents--all:ro |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
filters | No | object | Possible request filters |
filters.group_ids | No | int[] | IDs of the groups from which you want to list Agents. You'll only get the Agents from the specified group(s). |
fields * | No | string[] | Additional Agent fields to include. |
* Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
groups | Groups an Agent belongs to |
work_scheduler | Work scheduler object for an Agent |
email_subscriptions | A list of the Agent's active email subscriptions |
notifications | A list of the Agent's enabled notifications |
job_title | Agent's job title |
mobile | Agent's mobile number |
max_chats_count | Agent's maximum number of concurrent chats |
suspended | Boolean value indicating if an Agent is suspended |
awaiting_approval | Boolean value indicating if an Agent is awaiting approval |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_agents \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"fields": [
"summaries",
"max_chats_count",
"job_title"
],
"filters": {
"group_ids": [
0,
1
]
}
}'
[
{
"id": "smith@example.com",
"job_title": "Support Hero",
"max_chats_count": 5,
"summaries": [
"daily_summary",
"weekly_summary"
]
},
{
"id": "adam@example.com",
"job_title": "Support Hero (Newbie)",
"max_chats_count": 2,
"summaries": [
"weekly_summary"
]
}
]
Update Agent
Updates the properties of an Agent specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/update_agent |
Required scopes | agents--my:rw agents--all:rw (to update other Agents within the same license) |
Request
Parameter | Data type | Required | Notes |
---|---|---|---|
id | string | Yes | Agent ID |
name | string | No | Agent name |
role | string | No | Agent role, should be one of the following: viceowner , administrator , normal |
avatar_path | string | No | URL path for Agent avatar |
job_title | string | No | Agent's job title |
mobile | string | No | Agent's mobile number |
max_chats_count | int | No | Agent's maximum number of concurrent chats |
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. |
notifications ** | string[] | No | Represents which Agent notifications are turned on. |
email_subscriptions *** | string[] | No | Represents which subscriptions will be send to an Agent via email. |
work_scheduler | object | No | Work scheduler options to set for a new Agent |
work_scheduler.****.<work_scheduler> | object | No | <work_scheduler> values ***** |
* 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. Corresponds to the Primary priority option in the LiveChat App. |
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. Corresponds to the Secondary priority option in the LiveChat App. |
** Possible values for the notifications
array:
new_visitor
incoming_chat
returning_visitor
queued_visitor
visitor_is_typing
new_goal
unassigned_chats
unassigned_chat_messages
ticket
inactive_notifications
mute_all_sounds
repeat_sound_notifications
ticket_notifications
*** Possible values for the email_subscriptions
array:
daily_summary
weekly_summary
**** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
*****
<work_scheduler>
contains the following fields:
start
(string
) - the time when the Agent starts work, in the format:HH:MM
end
(string
) - the time when the Agent finishes work, in the format:HH:MM
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/update_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com",
"name": "Agent Smith",
"role": "viceowner",
"groups": [
{
"id": 5,
"priority": "first"
},
{
"id": 2,
"priority": "last"
},
{
"id": 1,
"priority": "normal"
}
],
"work_scheduler": {
"monday": {
"start": "08:30",
"end": "12:30"
},
"friday": {
"start": "07:30",
"end": "21:30"
}
},
"notifications": [
"new_visitor",
"new_goal",
"visitor_is_typing"
],
"email_subscriptions": [
"weekly_summary"
]
}'
Delete Agent
Deletes an Agent specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/delete_agent |
Required scopes | agents--all:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Agent ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/delete_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
Suspend Agent
Suspends an Agent specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/suspend_agent |
Required scopes | agents--all:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Agent ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/suspend_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
Unsuspend Agent
Unsuspends an Agent specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/unsuspend_agent |
Required scopes | agents--all:rw billing:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Agent ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/unsuspend_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
Request Agent Unsuspension
A suspended Agent can send emails to license owners and vice owners with an unsuspension request.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/request_agent_unsuspension |
Required scopes | - |
Request
Empty request payload.
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/request_agent_unsuspension \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Approve Agent
Approves an Agent thus allowing the Agent to use the application.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/approve_agent |
Required scopes | agents-all:rw subscription_manage * |
* subscription_manage
is a private scope; it's not possible to configure it in Developer Console.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Agent ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/approve_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
Bots
Bot enables writing integrations using the Agent Chat API - both RTM and Web - to communicate in chats as regular Agents.
A Bot shares the SSO access token with the Agent who created the Bot. Each Bot is a resource owned by an application in Developers Platform, identified by its own client_id
.
Unlike Agents, Bot don't have passwords or emails - you cannot log in as a Bot.
Methods
HTTP method | The Bots API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.2/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Create Bot
Creates a new Bot.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/create_bot |
Required scopes | agents-bot--my:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
name | Yes | string | Display name |
avatar | No | string | Avatar URL |
max_chats_count | No | int | Max. number of incoming chats that can be routed to the Bot; default: 6. |
default_group_priority ***** | No | string | The default routing priority for a group without defined priority. |
groups | No | object[] | Groups the Bot belongs to. |
groups[].id | No | int | Group ID; required only when group 's included. |
groups[].priority * | Yes | string | Bot's priority in a group; required only when group 's included. |
webhooks | No | object | Webhooks sent to the Bot; for more info on possible values and payload, see Webhooks. Webhooks work only for online Bots. |
webhooks.url | Yes | string | Destination URL for webhooks; required only when webhooks is included. |
webhooks.secret_key | Yes | string | Secret sent in webhooks to verify webhook's source; required only when webhooks 's included. |
webhooks.actions | Yes | object[] | Triggering actions; required only when webhooks 's 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 that will arrive with webhooks. |
work_scheduler | No | object | Work scheduler options to set for the new Bot. ** |
work_scheduler.***.<work_scheduler> | No | object | <work_scheduler> values ****. |
* 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. Corresponds to the Bot priority option in the LiveChat App. |
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. Corresponds to the Primary priority option in the LiveChat App. |
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. Corresponds to the Secondary priority option in the LiveChat App. |
** When using work_scheduler
, timezone for operating hours is the same as timezone of agent sending request
*** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
**** <work_scheduler>
contains the following fields:
start
(string
) - the time when the Bot starts accepting chats, in the format:HH:MM
end
(string
) - the time when the Bot finishes accepting chats, in the format:HH:MM
***** 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. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/create_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Bot Name"
}'
{
"bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}
Delete Bot
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/delete_bot |
Required scopes | agents-bot--my:rw agents-bot--all:rw |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
bot_agent_id | Yes | string | Bot ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/delete_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"bot_agent_id": "505591fc9fc2d6e92798bed7d9d8f079"
}'
Update Bot
Updates an existing Bot.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/update_bot |
Required scopes | agents-bot--my:rw agents-bot--all:rw (to update other Bots within the same license) |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Bot ID |
name | No | string | Display name |
avatar | No | string | Avatar URL |
max_chats_count | No | int | Maximum incoming chats that can be routed to the Bot. |
groups | No | object[] | Groups the Bot belongs to |
groups[].id | Yes | uint | Group ID, required only when groups 's present. |
groups[].priority * | Yes | string | Bot'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 the Bot. 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. |
work_scheduler | No | object | Work scheduler options to set for the new Bot. *** |
work_scheduler.****.<work_scheduler> | No | object | <work_scheduler> values *. |
* 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. Corresponds to the Bot priority option in the LiveChat App. |
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. Corresponds to the Primary priority option in the LiveChat App. |
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. Corresponds to the Secondary priority option in the LiveChat App. |
** 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. |
*** When using work_scheduler
, timezone for operating hours is the same as timezone of agent sending request
**** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
* <work_scheduler>
contains the following fields:
start
(string
) - the time when the Bot starts accepting chats, in the format:HH:MM
end
(string
) - the time when the Bot finishes accepting chats, in the format:HH:MM
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/update_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "ce54714e3d2b53adbfff09dbdbdd56e9",
"name": "New Bot Name"
}'
List Bots
Returns the list of Bots created within a license. The method behavior differs depending on who created the Bot and what authorization method is used for the call.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_bots |
Required scopes | agents-bot--my:ro agents-bot--all:ro |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
all | No | bool | true - gets all Bots within a license. Â false (default)* - returns only the requester's Bots. |
* Calling List Bots with all:false
- If a Bot was created via an app, all Agents who make the request via this app will get the Bot in the response.
- If a Bot was created directly by an Agent (PAT authorization), all Agents who authorize with PATs will get the Bot in the response.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_bots \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"all": false
}'
{
"bot_agents": [
{
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "John Doe",
"avatar": "https://example.com/avatar.jpg",
"status": "accepting chats"
}
]
}
Get Bot
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/get_bot |
Required scopes | agents-bot--my:ro agents-bot--all:ro |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
bot_agent_id | Yes | string | Bot ID |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/get_bot \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}'
{
"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",
"filters": {
"chat_properties": {
"source": {
"type": {
"values": [
"facebook",
"twitter"
]
}
}
}
}
},
{
"name": "incoming_event",
"additional_data": [
"chat_properties"
]
}
]
}
}
}
Groups
Groups let you organize your work by creating teams with Agent and Bot members. You can use groups to do configuration based on shared settings (language, working hours, department) and to separate chat routing. It's worth mentioning that one Agent can belong to multiple groups at the same time. It's possible to configure routing priorities for Agents and Bots specifically per group.
Methods
HTTP method | The Groups API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.2/configuration/action/<action> |
Required header | Value |
---|---|
Content-Type | application/json |
Create Group
Creates a new group.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/create_group |
Required scopes | groups--all:rw |
Request
Request object | Data type | Required | Notes |
---|---|---|---|
name | string | Yes | Group name (up to 180 chars) |
language_code | string | No | The code of the group languange |
agent_priorities * | object | Yes | Agents' priorities in a group as a map in the "<id>": "<priority>" format. At least one Agent must have the normal priority. |
* The table below presents the possible values for the agent_priorities
map:
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. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/create_group \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Sports shoes",
"agent_priorities": {
"agent1@example.com": "normal",
"agent2@example.com": "normal",
"agent3@example.com": "last"
}
}'
{
"id": 19
}
Update Group
Updates an existing group.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/update_group |
Required scopes | groups--my:rw groups--all:rw (to update groups the requester is not a member of) |
Request
Request object | Data type | Required | Notes |
---|---|---|---|
id | int | Yes | Group ID |
name | string | No | Group name (up to 180 chars) |
language_code | string | No | The code of the group languange |
agent_priorities * | object | No | Agents' priorities in a group as a map in the "<id>": "<priority>" format. |
* The table below presents the possible values for the agent_priorities
map:
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. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/update_group \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": 19,
"name": "Sport shoes",
"agent_priorities": {
"agent1@example.com": "normal",
"agent2@example.com": "normal",
"agent3@example.com": "last"
}
}'
Delete Group
Deletes an existing group.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/delete_group |
Required scopes | groups--my:rw groups--all:rw (to delete groups the requester is not a member of) |
Request
Request object | Data type | Required | Notes |
---|---|---|---|
id | int | Yes | Group ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/delete_group \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": 19
}'
List Groups
Lists all the exisiting groups.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_groups |
Required scopes | groups--all:ro |
Request
Request object | Data type | Required | Notes |
---|---|---|---|
fields * | string[] | No | Additional fields to include. |
* Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
agent_priorities | An object containing Agents belonging to a group, along with their priorities. |
routing_status | The routing status of a group. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_groups \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
[
{
"id": 0,
"name": "General",
"language_code": "en",
"routing_status": "offline"
},
{
"id": 19,
"name": "Sport shoes",
"language_code": "en",
"routing_status": "offline"
}
]
Get Group
Returns details about a group specified by its id
.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/get_group |
Required scopes | groups--my:ro groups--all:ro (to get groups the requester is not a member of) |
Request
Request object | Data type | Required | Notes |
---|---|---|---|
id | int | Yes | Group ID |
fields * | string[] | No | Additional fields to include. |
* Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
agent_priorities | An object containing Agents belonging to a group, along with their priorities. |
routing_status | The routing status of a group. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/get_group \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": 19,
"fields": ["agent_priorities", "routing_status"]
}'
{
"id": 19,
"name": "Sports shoes",
"language_code": "en",
"agent_priorities": {
"agent1@example.com": "normal",
"agent2@example.com": "normal",
"agent3@example.com": "last"
},
"routing_status": "offline"
}
Properties
Properties are key-value storages. They can be set within a specific location.
You can register 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 within the following locations:
- chat
- thread
- event
- license
- group
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
to3
).
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 format
{
"properties": {
"<namespace>": {
"<property_name>": "<property_value>",
"<property_name>": "<property_value>"
}
}
}
Methods
HTTP method | The Properties API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.2/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Register Properties
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/register_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 , license , group |
<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
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/register_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"string_property": {
"type": "string",
"locations": {
"chat": {
"access": {
"agent": {
"read": true,
"write": true
},
"customer": {
"read": true,
"write": true
}
}
},
// "thread": {},
// "event": {},
// "license": {},
// "group": {}
}
}
}'
List Registered Properties
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_registered_properties |
Required scopes | properties--my:ro properties--all:ro (to list 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 . |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_registered_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'
{
"0805e283233042b37f460ed8fbf22160": {
"string_property": {
"type": "string",
"description": "",
"locations": {
"thread": {
"access": {
"agent": {
"read": true,
"write": true
},
"customer": {
"read": true,
"write": true
}
}
},
"chat": {
"access": {
"agent": {
"read": true,
"write": true
},
"customer": {
"read": true,
"write": true
}
}
}
}
}
}
}
Update License Properties
Updates a property value within a license. This operation doesn't overwrite the existing values.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/update_license_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, setting license properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
properties | Yes | object | An object with namespaces as keys and properties (grouped in objects) as values. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/update_license_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
}'
{}
List License Properties
Returns the properties set within a license.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_license_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, retrieving license properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.read
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
namespace_prefix | No | string | Properties namespace prefix |
name_prefix | No | string | Properties name prefix |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_license_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"namespace_prefix": "0",
"name_prefix": "string"
}'
{
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
Delete License Properties
Deletes the properties set within a license.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/delete_license_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, deleting license properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
properties | Yes | object | An object with namespaces as keys and property_names (in an array) as values. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/delete_license_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"properties": {
"0805e283233042b37f460ed8fbf22160": ["string_property"]
}
}'
Update Group Properties
Updates a property value within a group as the property location. This operation doesn't overwrite the existing values.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/update_group_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, setting group properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
group_id | Yes | number | ID of the group you set the properties for. |
properties | Yes | object | An object with namespaces as keys and properties (grouped in objects) as values. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/update_group_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"group_id": 1,
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "group property value"
}
}
}'
{}
List Group Properties
Returns the properties set within a group.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_group_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, retrieving group properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.read
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
group_id | Yes | number | ID of the group you retrieve properties from. |
namespace_prefix | No | string | Properties namespace prefix |
name_prefix | No | string | Properties name prefix |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_group_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"group_id": 1,
"namespace_prefix": "0",
"name_prefix": "string"
}'
{
"0805e283233042b37f460ed8fbf22160": {
"string_property": "group property value"
}
}
Delete Group Properties
Deletes the properties set within a group.
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/delete_group_properties |
Required scopes* | - |
*) If the requester's Client ID matches the namespace, deleting group properties is always allowed.
Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write
.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
group_id | Yes | number | ID of the group you delete properties from. |
properties | Yes | object | An object with namespaces as keys and property_names (in an array) as values. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/delete_group_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"group_id": 1,
"properties": {
"0805e283233042b37f460ed8fbf22160": ["string_property"]
}
}'
Webhooks
Here's what you need to know about webhooks:
- Webhooks notify you when specific events are triggered.
- They can be generated by both Web and RTM API actions.
- Webhooks and pushes have similar payloads.
Available webhooks
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "<action>",
"license_id": "<license_id>",
"payload": {
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Chats
incoming_chat
Informs about a chat coming with a new thread. The webhook payload contains the whole chat data structure. If the chat was started with some initial events, the thread object contains them.
Specifics
Action | incoming_chat |
Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
Object | Notes |
---|---|
chat | Chat data structure |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_chat",
"license_id": 104130623,
"payload": {
"chat": {
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"properties": {
// "Property" object
},
"thread": {
// "Thread" object
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
chat_deactivated
Informs that a chat was deactivated by closing the currently open thread.
Specifics
Action | chat_deactivated |
Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
Object | Notes |
---|---|
user_id | Missing if a thread was closed by the router. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_deactivated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Chat access
chat_access_granted
Informs that new, single access to a chat was granted. The existing access isn't overwritten.
Specifics
Action | chat_access_granted |
Push equivalent in | Agent Chat API |
Webhook payload
Object | Notes |
---|---|
id | Chat id |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_access_granted",
"license_id": 104130623,
"payload": {
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
chat_access_revoked
Informs that access to a certain chat was revoked.
Specifics
Action | chat_access_revoked |
Push equivalent in | Agent Chat API |
Webhook payload
Object | Notes |
---|---|
id | Chat Id |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_access_revoked",
"license_id": 104130623,
"payload": {
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Chat users
user_added_to_chat
Informs that a user (Customer or Agent) was added to a chat.
Specifics
Action | user_added_to_chat |
Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
Object | Notes |
---|---|
user_type | Possible values: agent , customer |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "user_added_to_chat",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user": {
// "User > Customer" or "User > Agent" object
},
"reason": "manual",
"requester_id": "smith@example.com"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
user_removed_from_chat
Informs that a user (Customer or Agent) was removed from a chat.
Specifics
Action | user_removed_from_chat |
Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
Object | Notes |
---|---|
user_type | Possible values: agent , customer |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "user_removed_from_chat",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "agent@example.com",
"reason": "manual",
"requester_id": "smith@example.com"
},
"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 |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_event",
"license_id": 104130623,
"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 |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_updated",
"license_id": 104130623,
"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 |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_rich_message_postback",
"license_id": 104130623,
"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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
},
"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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_properties_updated
Informs about those thread properties that were updated.
Specifics
Action | 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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_properties_deleted
Informs about those thread properties that were deleted.
Specifics
Action | 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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "property_value"
}
}
},
"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. |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Thread tags
thread_tagged
Informs that a thread was tagged.
Specifics
Action | thread_tagged |
Push equivalent in | Agent Chat API |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_tagged",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_untagged
Informs that a thread was untagged.
Specifics
Action | thread_untagged |
Push equivalent in | Agent Chat API |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_untagged",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Status
routing_status_set
Informs that an Agent's or Bot's status has changed.
Specifics
Action | routing_status_set |
Push equivalent in | Agent Chat API |
Webhook payload
Object | Notes |
---|---|
status | Possible values: accepting chats , not accepting chats , offline (for Bots only) |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "routing_status_set",
"license_id": 104130623,
"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 | - |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "agent_deleted",
"license_id": 104130623,
"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 |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "customer_created",
"license_id": 104130623,
"payload": {
"customer": {
// "User > Customer" object
}
},
"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 |
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "events_marked_as_seen",
"license_id": 104130623,
"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.2/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Register Webhook
Specifics
Method URL | https://api.livechatinc.com/v3.2/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 arriving with the webhook. Value: chat properties (all actions except for agent_status_changed , agent_deleted , customer_created ) |
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 the 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 | Available filters |
---|---|
incoming_chat | chat_member_ids , only_my_chats |
chat_deactivated | chat_member_ids , only_my_chats |
chat_access_granted | chat_member_ids , only_my_chats |
chat_access_revoked | chat_member_ids , only_my_chats |
user_added_to_chat | chat_member_ids , only_my_chats |
user_removed_from_chat | chat_member_ids , only_my_chats |
incoming_event | chat_member_ids , author_type , only_my_chats |
event_updated | chat_member_ids , author_type , only_my_chats |
incoming_rich_message_postback | chat_member_ids , only_my_chats |
chat_properties_updated | chat_member_ids , only_my_chats |
chat_properties_deleted | chat_member_ids , only_my_chats |
thread_properties_updated | chat_member_ids , only_my_chats |
thread_properties_deleted | chat_member_ids , only_my_chats |
event_properties_updated | chat_member_ids , only_my_chats |
event_properties_deleted | chat_member_ids , only_my_chats |
thread_tagged | chat_member_ids , only_my_chats |
thread_untagged | chat_member_ids , only_my_chats |
routing_status_set | - |
agent_deleted | chat_member_ids , agent_ids |
customer_created | - |
events_marked_as_seen | chat_member_ids , only_my_chats |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/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": "chat_deactivated",
"secret_key": "laudla991lamda0pnoaa0"
}'
{
"webhook_id": "pqi8oasdjahuakndw9nsad9na"
}
List Registered Webhooks
Specifics
Method URL | https://api.livechatinc.com/v3.2/configuration/action/list_registered_webhooks |
Required scopes | webhooks--my:ro webhooks--all:ro |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/configuration/action/list_registered_webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'
[
{
"webhook_id": "pqi8oasdjahuakndw9nsad9na",
"url": "http://myservice.com/webhooks",
"description": "Test webhook",
"action": "chat_deactivated",
"filters": {
"chat_member_ids": {
"agents_any": [
"johndoe@mail.com"
]
}
},
"owner_client_id": "asXdesldiAJSq9padj"
}
]
Unregister Webhook
Specifics
Method URL | https://api.livechatinc.com/v3.2/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
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.2/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!