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.3, which is a legacy version. For production-ready applications, it's best to use to the current stable version. Read more about versioning...
Lifecycle headers
API responses will contain one of two headers related to the API lifecycle: Legacy
or Deprecation
. These headers specify when the associated stage ends (in the YYYY-MM-DD
format).
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 OAuth 2.1 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.
If you get the misdirected_request
error, use the prefix returned in the error as the value of X-Region
.
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.3 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 sample tokens with your own.
Agents
An agent is a type of user who communicates with customers. You can look up the sample agent data structure in the response of Get Agent.
Methods
HTTP method | The Agents API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.3/configuration/action/<action> |
Required header | Value |
---|---|
Content-Type | application/json |
Create Agent
Creates a new agent with specified parameters within a license.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/create_agent |
Required scopes | accounts--all:rc accounts--all:rw 1 subscription.lc:rw 1 2 accounts.roles.lc--all:rw 3 |
1) – to create agents who don't have to wait for approval after creation
2) – subscription.lc:rw
is a private scope; it's not possible to configure it in Developer Console.
3) – to create an agent with role higher than normal
(administrator
, viceowner
or owner
)
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 | Avatar URL |
login_status | string | No | Agent's default status right after the login, should be one of the following: accepting chats , not accepting chats (default). |
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; default: 6. Limited to 100. |
awaiting_approval | bool | No | Determines if the Agent will be awaiting approval after creation. Only a requester with the subscription.lc: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 4 | string | Yes | Agent's priority in a group; required only when group is included. |
notifications 5 | string[] | No | Represents which Agent notifications are turned on. |
email_subscriptions 6 | 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 7 |
4) 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. |
supervisor | Agents with the supervisor priority will not get any chats assigned automatically. |
5) 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
incoming_message_for_focused_chat
6) 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
7) <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.3/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.3/configuration/action/get_agent |
Required scopes | agents--my:ro agents--all:ro |
Request
Parameter | Type | Required | Notes |
---|---|---|---|
id | string | Yes | Agent ID |
fields 1 | string[] | No | Additional fields to include. |
1) Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
work_scheduler 2 | 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 |
2) This method doesn’t support the new version of work_scheduler
(see parameters in Create Agent). Requesting it in the call might result in the validation
error.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/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.3/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 1 | No | string[] | Additional Agent fields to include. |
1) Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
groups | Groups an Agent belongs to |
work_scheduler 2 | 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 |
2) This method doesn’t support the new version of work_scheduler
(see parameters in Create Agent). Requesting it in the call might result in the validation
error.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/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
]
}
}'
[
{
"avatar_path": "cdn.livechatinc.com/avatars/1.png",
"id": "smith@example.com",
"job_title": "Support Hero",
"login_status": "not accepting chats",
"name": "Smith",
"role": "owner",
"max_chats_count": 5,
"summaries": [
"daily_summary",
"weekly_summary"
]
},
{
"avatar_path": "cdn.livechatinc.com/avatars/2.png",
"id": "jones@example.com",
"job_title": "Support Hero (Newbie)",
"login_status": "accepting chats",
"name": "Jones",
"role": "viceowner",
"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.3/configuration/action/update_agent |
Required scopes | agents--my:rw agents--all:rw 1 accounts.roles.lc--all:rw 2 |
1) to update other agents within the same license
2) to update the agent role
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 | Avatar URL |
login_status | string | No | Agent's default status right after the login, should be one of the following: accepting chats , not accepting chats (default). |
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. Limited to 100. |
groups | object[] | No | Groups an Agent belongs to. |
groups[].id | uint | Yes | Group ID; required only when group 's included. |
groups[].priority 3 | string | Yes | Agent's priority in a group; required only when group 's included. |
notifications 4 | string[] | No | Represents which Agent notifications are turned on. |
email_subscriptions 5 | 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 6 |
3) 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. |
supervisor | Agents with the supervisor priority will not get any chats assigned automatically. |
4) 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
incoming_message_for_focused_chat
5) 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
6)
<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.3/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.3/configuration/action/delete_agent |
Required scopes | agents--my:rw accounts--my:rw agents--all:rw 1 accounts--all:rw 1 |
1) to delete other agents within the same license
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.3/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
.
❗️ This method is not yet available for public use. For now, an agent can only be approved via the LiveChat Agent application UI. We would love to hear how you'd like to use this method -- please send us an email at developers@text.com describing your use case.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/suspend_agent |
Required scopes | agents--all:rw sessions--all:rw 1 |
1) sessions--all:rw
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.3/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
.
❗️ This method is not yet available for public use. For now, an agent can only be approved via the LiveChat Agent application UI. We would love to hear how you'd like to use this method -- please send us an email at developers@text.com describing your use case.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/unsuspend_agent |
Required scopes | agents--all:rw accounts--all:rw subscription.lc:rw 1 |
1) subscription.lc:rw
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.3/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.3/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.3/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.
❗️ This method is not yet available for public use. For now, an agent can only be approved via the LiveChat Agent application UI. We would love to hear how you'd like to use this method -- please send us an email at developers@text.com describing your use case.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/approve_agent |
Required scopes | agents--all:rw accounts--all:rw subscription.lc:rw 1 |
1) subscription.lc:rw
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.3/configuration/action/approve_agent \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "smith@example.com"
}'
Auto access
Auto access allows you to assign groups to a thread that will be created when a customer starts a chat. Those groups are assigned based on the conditions defined to match the customer's geolocation and the page URL the customer is currently visiting. Every time a customer calls Login or Update Customer Page, our backend checks if the page URL and geolocation match the pre-defined conditions. Given there's a match, the groups are assigned to a thread, but not until a chat starts and the thread is actually created.
If a customer starts a chat via Start Chat or
Activate Chat with the chat.access
parameter,
chat.access
overrides the auto access assigned to the thread.
Auto access rules are ordered using a linked list. Each of them points to the next element by keeping its id
in the next_id
field.
For the last element of the list, the next_id
is empty.
Methods
Add Auto Access
Creates an auto access
data structure, which is a set of conditions for the tracking URL and geolocation of a customer.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/add_auto_access |
Required scopes | access_rules:rw |
Parameter | Required | Data type | Notes |
---|---|---|---|
access | Yes | object | Destination access |
access.groups | Yes | []int | Destination groups |
conditions 1 | Yes | object | Conditions to check |
conditions.url | No | object | The condition that matches on customer_page.url from Login or url from Update Customer Page |
conditions.domain | No | object | The condition that matches on the domain of the customer_url |
conditions.{url,domain}.values | No | []match_object 2 | Positive match, may not be used together with exclude_values |
conditions.{url,domain}.exclude_values | No | []match_object | Negative match |
conditions.geolocation | No | object | The condition that matches on the customer's geolocation |
conditions.geolocation.values | Yes | []geolocation_object 3 | An array of objects; matches when at least one subcondition matches. |
description | No | string | Description of the auto access |
next_id | No | string | ID of an existing auto access. Leave empty if the new auto access should be the last one on the list. |
1) conditions
must have at least one of url
, domain
, geolocation
set.
2) <match_object>
structure:
Parameter | Required | Data type | Notes |
---|---|---|---|
value | Yes | string | A value to match |
exact_match | No | bool | If set to false , a match_object.value will be matched as a substring of the customer URL or domain. |
3) the geolocation_object
structure. The condition is fulfilled only when all of the specified fields match. At least one field must be specified.
Parameter | Required | Data type | Example |
---|---|---|---|
country | No | string | "United States" |
country_code | No | string | "US" |
region | No | string | "California" |
city | No | string | "Mountain View" |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/add_auto_access \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"description": "Chats on livechat.com from United States",
"access": {
"groups": [ 1 ]
},
"conditions": {
"domain": {
"values": [
{
"value": "livechat.com",
"exact_match": true
}
]
},
"geolocation": {
"values": [
{
"country": "United States",
"country_code": "US"
}
]
}
},
"next_id": "1faad6f5f1d6e8fdf27e8af9839783b7"
}'
{
"id": "pqi8oasdjahuakndw9nsad9na"
}
List Auto Accesses
Returns all existing auto access
data structures.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_auto_accesses |
Required scopes | access_rules:ro |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_auto_accesses \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{}'
[
{
"id": "1faad6f5f1d6e8fdf27e8af9839783b7",
"description": "Chats on livechat.com from United States",
"access": {
"groups": [
0
]
},
"conditions": {
"geolocation": {
"values": [
{
"country": "United States",
"country_code": "US"
}
]
},
"domain": {
"values": [
{
"value": "livechat.com",
"exact_match": true
}
]
}
},
"next_id": "pqi8oasdjahuakndw9nsad9na"
}
]
Delete Auto Access
Deletes an existing auto access
data structure specified by its ID.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/delete_auto_access |
Required scopes | access_rules:rw |
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Auto access ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/delete_auto_access \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"id": "pqi8oasdjahuakndw9nsad9na"
}'
Update Auto Access
Updates an existing auto access
. Only specified fields are updated (overwritten), leaving unspecified fields unchanged.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/update_auto_access |
Required scopes | access_rules:rw |
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | ID of the auto access to modify |
access | No | object | Destination access |
access.groups | Yes | []int | Destination groups |
conditions 1 | No | object | Conditions to check |
conditions.url | No | object | The condition that matches on customer_page.url from Login or url from Update Customer Page |
conditions.domain | No | object | The condition that matches on the domain of the customer_url |
conditions.{url,domain}.values | No | []match_object 2 | Positive match, may not be used together with exclude_values |
conditions.{url,domain}.exclude_values | No | []match_object | Negative match |
conditions.geolocation | No | object | The condition that matches on the customer's geolocation |
conditions.geolocation.values | Yes | []geolocation_object 3 | An array of objects; matches when at least one subcondition matches. |
description | No | string | Description of the auto access |
next_id 4 | No | string | ID of an existing auto access. If next_id is an empty string, auto_access moves to the end of the list. |
1) conditions
must have at least one of url
, domain
, geolocation
set.
2) <match_object>
structure:
Parameter | Required | Data type | Notes |
---|---|---|---|
value | Yes | string | A value to match |
exact_match | No | bool | If set to false , a match_object.value will be matched as a substring of the customer URL or domain; default: false. |
3) the geolocation_object
structure. The condition is fulfilled only when all of the specified fields match. At least one field must be specified.
Parameter | Required | Data type | Example |
---|---|---|---|
country | No | string | "United States" |
country_code | No | string | "US" |
region | No | string | "California" |
city | No | string | "Mountain View" |
4) Modifying next_id
moves the auto access specified by id
before the auto access that is specified by next_id
.
If next_id
is an empty string, then auto access will be placed at the end of the list. If you don't intend to reorder the rule at all, don't include next_id
in the request. To better understand it, analyze the example below.
💡 Example:
In the following list: A -> B -> C -> D -> null, letters represent the auto_access
data structures while arrows indicate the next_id
relation. Therefore, A has next_id
set to B, B has next_id
set to C, and so on.
An update_auto_access
call with the {"id": "C", "next_id": "B"}
payload would result in reordering the sequence, which after the successful request, would look like this: A -> C -> B -> D -> null. Consistency is maintained by keeping the next_id
references properly assigned in each of the elements after a single request.
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/update_auto_access \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"id": "pqi8oasdjahuakndw9nsad9na",
"access": {
"groups": [0, 42]
},
"next_id": "1faad6f5f1d6e8fdf27e8af9839783b7"
}'
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.3/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Create Bot
Creates a new bot. To make the bot available for receiving chats or webhooks, use the Set Routing Status method.
Specifics
Method URL | https://api.livechatinc.com/v3.3/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. Limited to 500. |
default_group_priority 4 | No | string | The default routing priority for a group without defined priority. |
job_title | No | string | Bot's job title |
groups | No | object[] | Groups the Bot belongs to. |
groups[].id | No | int | Group ID; required only when group 's included. |
groups[].priority 1 | Yes | string | Bot's priority in a group; required only when group 's included. |
work_scheduler | No | object | Work scheduler options to set for the new Bot. |
work_scheduler.**.<work_scheduler> | No | object | <work_scheduler> values 3. |
timezone | Yes | string | The time zone in which the Bot's work scheduler should operate. Required only if work_scheduler is provided. |
owner_client_id 5 | Yes | string | Required only when authorizing via PATs. The request will be rejected if you provide owner_client_id when authorizing with a Bearer Token. |
1) Possible values for the groups[].priority
parameter:
Possible values | Notes |
---|---|
first | The highest chat routing priority. Bots 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. Bots with the normal priority get chats before agents 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. Bots 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. |
supervisor | Bots with the supervisor priority will not get any chats assigned automatically. |
** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
3) <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
4) The table below presents the possible values for the default_group_priority
parameter:
Possible values | Notes |
---|---|
first | The highest chat routing priority. Bots 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. Bots with the normal priority get chats before agents 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. Bots 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. |
supervisor | Bots with the supervisor priority will not get any chats assigned automatically. |
5) The number of sent webhooks depends on the number of webhooks registered for an owner_client_id
, not the number of bots belonging to that owner_client_id
.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/create_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Bot Name"
}'
{
"id": "5c9871d5372c824cbf22d860a707a578"
}
Delete Bot
Deletes a bot specified by id
.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/delete_bot |
Required scopes | agents-bot--my:rw agents-bot--all:rw |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
id | Yes | string | Bot ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/delete_bot \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "505591fc9fc2d6e92798bed7d9d8f079"
}'
Update Bot
Updates an existing Bot.
Specifics
Method URL | https://api.livechatinc.com/v3.3/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. Limited to 500. |
groups | No | object[] | Groups the Bot belongs to |
groups[].id | Yes | uint | Group ID, required only when groups 's present. |
groups[].priority 1 | Yes | string | Bot's priority in the group; required only when groups is included. |
default_group_priority 2 | No | string | The default routing priority for a group without defined priority. |
work_scheduler | No | object | Work scheduler options to set for the new Bot. |
work_scheduler.***.<work_scheduler> | No | object | <work_scheduler> values 4. |
timezone | No | string | The time zone in which the Bot's work scheduler should operate. Required if work_scheduler is provided. |
1) The table below presents the possible values for the groups[].priority
parameter:
Possible values | Notes |
---|---|
first | The highest chat routing priority. Bots 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. Bots with the normal priority get chats before agents 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. Bots 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. |
supervisor | Bots with the supervisor priority will not get any chats assigned automatically. |
2) The table below presents the possible values for the default_group_priority
parameter:
Possible values | Notes |
---|---|
first | The highest chat routing priority. Bots 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. Bots with the normal priority get chats before agents 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. Bots 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. |
supervisor | Bots with the supervisor priority will not get any chats assigned automatically. |
*** Possible values for the work_scheduler
object keys:
sunday
monday
tuesday
wednesday
thursday
friday
saturday
4) <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.3/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.3/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)1 - returns only the requester's Bots. |
fields 2 | No | string[] | Additional Bot fields to include |
1) 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.
2) Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
groups | Groups a Bot belongs to |
work_scheduler 3 | Work scheduler object for a Bot |
job_title | Bot's job title |
max_chats_count | Bot's maximum number of concurrent chats |
timezone | The time zone in which the Bot's work scheduler operates |
3) This method doesn’t support the new version of work_scheduler
(see parameters in Create Agent). Requesting it in the call might result in the validation
error.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_bots \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"all": false
}'
[
{
"id": "2c1b8da190222160e8f9e077af4c625b",
"name": "Bot Name",
"avatar_path": "example.com/avatar.jpg"
}
]
Get Bot
It returns the info about a bot with a given id
.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/get_bot |
Required scopes | agents-bot--my:ro agents-bot--all:ro |
Request
Parameter | Required | Type | Notes |
---|---|---|---|
id | Yes | string | Bot ID |
fields 1 | string[] | No | Additional fields to include. |
1) Possible values for the fields[]
parameter:
Possible value | Notes |
---|---|
work_scheduler 2 | Work scheduler object for a Bot |
groups | Groups a Bot belongs to |
job_title | Bot's job title |
max_chats_count | Bot's maximum number of concurrent chats |
timezone | The time zone in which the Bot's work scheduler operates |
2) This method doesn’t support the new version of work_scheduler
(see parameters in Create Agent). Requesting it in the call might result in the validation
error.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/get_bot \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"id": "5c9871d5372c824cbf22d860a707a578"
}'
{
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "John Doe",
"avatar_path": "https://example.com/avatar.jpg",
"default_group_priority": "first",
"owner_client_id": "asXdesldiAJSq9padj",
"max_chats_count": 6,
"groups": [
{
"id": 0,
"priority": "normal"
},
{
"id": 1,
"priority": "normal"
},
{
"id": 2,
"priority": "first"
}
]
}
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.3/configuration/action/<action> |
Required header | Value |
---|---|
Content-Type | application/json |
Create Group
Creates a new group.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/create_group |
Required scopes | groups--all:rw |
Request
Parameter | 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 1 | object | Yes | Agents' priorities in a group as a map in the "<id>": "<priority>" format. At least one Agent must have the normal priority. |
1) 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. |
supervisor | Agents with the supervisor priority will not get any chats assigned automatically. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/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.3/configuration/action/update_group |
Required scopes | groups--my:rw groups--all:rw (to update groups the requester is not a member of) |
Request
Parameter | 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 1 | object | No | Agents' priorities in a group as a map in the "<id>": "<priority>" format. |
1) 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. |
supervisor | Agents with the supervisor priority will not get any chats assigned automatically. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/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.3/configuration/action/delete_group |
Required scopes | groups--my:rw groups--all:rw (to delete groups the requester is not a member of) |
Request
Parameter | Data type | Required | Notes |
---|---|---|---|
id | int | Yes | Group ID |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/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.3/configuration/action/list_groups |
Required scopes | groups--all:ro |
Request
Parameter | Data type | Required | Notes |
---|---|---|---|
fields 1 | string[] | No | Additional fields to include. |
1) 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.3/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.3/configuration/action/get_group |
Required scopes | groups--my:ro groups--all:ro (to get groups the requester is not a member of) |
Request
Parameter | Data type | Required | Notes |
---|---|---|---|
id | int | Yes | Group ID |
fields 1 | string[] | No | Additional fields to include. |
1) 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.3/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. Property configuration is owned by a Client Id (integration). In this document, we call a Client Id that owns a property the owner Client Id.
Properties can be private or public.
- Private properties can be accessed only by their owner Client Id. Read more...
- Public properties can be accessed by any Client Id. Read more...
Properties are grouped in namespaces, which helps to distinguish which property belongs to a given Client Id. The property namespace is named after the Client Id a property belongs to.
You can configure the property type, location access, and domain.
The general properties format
{
"properties": {
"<namespace>": {
"<property_name>": "<property_value>",
"<property_name>": "<property_value>"
}
}
}
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:
- event
- thread
- chat
- group
- license
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
).
Property default value
If a property value hasn't been explicitly set, then the default value will be returned, if any.
The default value of a property can be set during property registration as the default_value
parameter.
Private properties
You can register, unregister, and configure a property for a Client Id owned by your organization. Unpublished (private) properties can be access only with a token belonging to the owner Client Id. If you want other integrations to be able to access your private property, you need to publish it.
Public properties
Once you publish a private property, it becomes accessible to other integrations. The public access to your property can be read
and/or write
. Consider an example:
You register a private chat property with the read
and write
access.
{
"name": "string_property",
"owner_client_id": "0805e283233042b37f460ed8fbf22160",
"type": "string",
"access": {
"chat": {
"agent": ["read"],
"customer": ["read", "write"]
}
}
}
While publishing the property, you can narrow down its public access to read
.
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/publish_property \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"name": "string_property",
"owner_client_id": "0805e283233042b37f460ed8fbf22160",
"access_type": ["read"]
}'
In this case, tokens belonging to the owner Client Id will be able to read and write to that property. Any other token will only be able to read it.
💡 Published properties cannot be unregistered.
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.
Predefined properties
There are also predefined public properties used mainly by the LiveChat backend integration.
Methods
HTTP method | The Properties API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.3/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Register Property
Registers a new private property for a given Client Id.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/register_property |
Required scopes | properties.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
name | Yes | string | Property name |
owner_client_id | Yes | string | Client Id that will own the property; must be owned by your organization. |
type | Yes | string | Possible values: int , string , bool , and tokenized_string |
access | Yes | object | |
access.<location> | min. one location | object | Possible values: chat , thread , event , license , group |
access.<location>.<user> | min. one user | [string] | Possible <user> values: agent , customer ; possible values: read , write |
description | No | string | Property description |
domain 1 | No | [<type>] | Array of values that properties can be set to |
range 1 | No | object | Range of values that properties can be set to |
range.from | No | int | Only values equal or greater than this parameter can be set to this property |
range.to | No | int | Only values equal or lower than this parameter can be set to this property |
default_value 2 | No | type | Default value of property; validated by domain or range, if one exists |
1) Only one domain
and one range
can be set for a single property.
2) Registering a property with default_value
is possible only if access.<location>
is set to license
or to group
.
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/register_property \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"name": "string_property",
"owner_client_id": "0805e283233042b37f460ed8fbf22160",
"type": "string",
"default_value": "string_default_value",
"access": {
"chat": {
"agent": ["read"],
"customer": ["read", "write"]
}
// "thread": {},
// "event": {},
// "license": {},
// "group": {}
}
}'
Unregister Property
Unregisters a private property.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/unregister_property |
Required scopes | properties.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
name | Yes | string | Property name |
owner_client_id | Yes | string | Client Id that owns the property; must be owned by your organization |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/unregister_property \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"name": "string_property",
"owner_client_id": "0805e283233042b37f460ed8fbf22160"
}'
Publish Property
Publishes a private property. A published property cannot be unpublished or unregistered. Published properties can be accessed by tokens belonging to any Client Id.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/publish_property |
Required scopes | properties.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
name | Yes | string | Property name |
owner_client_id | Yes | string | Client Id that owns the property; must be owned by your organization. |
access_type | Yes | [string] | Possible values: read , write . It determines the access level for the Client Ids different than owner_client_id . |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/publish_property \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"name": "string_property",
"owner_client_id": "0805e283233042b37f460ed8fbf22160",
"access_type": ["read"]
}'
List Properties
Lists private and public properties owned by a given Client Id.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_properties |
Required scopes | properties.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
owner_client_id | Yes | string | Client Id that owns the properties; must be owned by your organization. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"owner_client_id": "0805e283233042b37f460ed8fbf22160"
}'
{
"string_property": {
"type": "string",
"description": "",
"access": {
"thread": {
"agent": [
"read",
"write"
],
"customer": [
"read"
]
},
"chat": {
"agent": [
"write"
],
"customer": [
"read",
"write"
]
}
},
"public_access": [
"read"
]
}
}
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.3/configuration/action/update_license_properties |
Required scopes | properties.license.value--my:rw 1, properties.license.value--all:rw 2 |
1) If the requester's Client ID matches the namespace, setting license properties requires properties.license.value--my:rw
.
2) If the requester's Client ID doesn't match the namespace, setting license properties requires properties.license.value--all:rw
. The scope allows to
set all properties from your namespace and public properties from core
and other namespaces.
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.3/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. For properties without an explicit value assignment, the method will return the default values (if they exist).
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_license_properties |
Required scopes | properties.license.value--my:ro 1, properties.license.value--all:ro 2 |
1) The properties.license.value--my:ro
scope allows you to access all properties from your namespace only.
2) The properties.license.value--all:ro
scope allows you to access all properties from your namespace and public properties from core
and other namespaces.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
namespace | No | string | Properties namespace |
name_prefix | No | string | Properties name prefix |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_license_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"namespace": "0805e283233042b37f460ed8fbf22160",
"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.3/configuration/action/delete_license_properties |
Required scopes | properties.license.value--my:rw 1, properties.license.value--all:rw 1 |
1) If the requester's Client ID matches the namespace, deleting license properties requires properties.license.value--my:rw
.
2) If the requester's Client ID doesn't match the namespace, deleting license properties requires properties.license.value--all:rw
. The scope allows to
delete all properties from your namespace and public properties from core
and other namespaces.
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.3/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.3/configuration/action/update_group_properties |
Required scopes | properties.group.value--my:rw 1, properties.group.value--all:rw 2 |
1) If the requester's Client ID matches the namespace, setting group properties requires properties.group.value--my:rw
.
2) If the requester's Client ID doesn't match the namespace, setting group properties requires properties.group.value--all:rw
. The scope allows to
set all properties from your namespace and public properties from other namespaces.
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.3/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. For properties without an explicit value assignment, the method will return the default values (if they exist).
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_group_properties |
Required scopes | properties.group.value--my:ro 1, properties.group.value--all:ro 2 |
1) The properties.group.value--my:ro
scope allows you to access all properties from your namespace only.
2) The properties.group.value--all:ro
scope allows you to access all properties from your namespace and public properties from core
and other namespaces.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | number | ID of the group you retrieve properties from. |
namespace | No | string | Properties namespace |
name_prefix | No | string | Properties name prefix |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_group_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"id": 1,
"namespace": "0805e283233042b37f460ed8fbf22160",
"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.3/configuration/action/delete_group_properties |
Required scopes | properties.group.value--my:rw 1, properties.group.value--all:rw 2 |
1) If the requester's Client ID matches the namespace, deleting group properties requires properties.group.value--my:rw
.
2) If the requester's Client ID doesn't match the namespace, deleting group properties requires properties.group.value--all:rw
. The scope allows to
delete all properties from your namespace and public properties from other namespaces.
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
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.3/configuration/action/delete_group_properties \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"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.
- You register webhook definitions per Client ID (application).
- Webhooks are always automatically enabled for the licences that install your application.
- There's a limit of three weebhoks for every action a Client ID can register.
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "<action>",
"license_id": "<license_id>",
"payload": {
},
"additional_data": {
"chat_properties": { //optional
// chat properties
},
"chat_presence_user_ids": [ //optional
// User IDs
]
}
}
Methods
HTTP method | The Webhooks API endpoint |
---|---|
POST | https://api.livechatinc.com/v3.3/configuration/action/<action> |
Required header | Value | |
---|---|---|
Content-Type | application/json |
Register Webhook
Registers a webhook for the Client ID (application) provided in the request. One Client ID can register up to three webhooks for every action
. The license
webhooks'll be enabled automatically when the application is installed on the license.
As an alternative to calling Register Webhook, you can register webhooks via Developer Console by configuring the Chat Webhooks building block. Learn more...
For bot
webhooks, you need to create a bot, register webhooks, and then, call Set Routing Status. The Chat Webhooks block in Developer Console doesn't support bot
webhooks.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/register_webhook |
Required token scopes 1 | webhooks.configuration:rw |
1) Token scopes are assigned to an access token, not to an application (Client ID). For this method, we recommend authorizing with a Personal Access Token (PAT). Make sure your PAT has the webhooks.configuration:rw
scope.
Parameter | Required | Data type | Notes |
---|---|---|---|
action 2 | 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 , chat_presence_user_ids (all actions except for agent_status_changed , agent_deleted , incoming_customer ) |
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_presence | no | object | Filters to check if a webhook should be triggered based on user's presence in the chat. |
filters.chat_presence.user_ids | no | object | Only one filter (values or exclude_values ) is allowed. Supports every user type (Agent, Customer, Bot). |
filters.chat_presence.user_ids.values | no | []string | Array of Users' ids; if any specified User is in the chat, the webhook will be triggered. |
filters.chat_presence.user_ids.exclude_values | no | []string | Array of Users' ids; if any specified Users is in the chat, the webhook will not be triggered. |
filters.chat_presence.my_bots | no | bool | If any bot owned by owner_client_id is in the chat, the webhook will be triggered. |
owner_client_id | yes | string | The Client ID for which the webhook will be registered. What is Client ID and where to find it? |
type | yes | string | bot or license |
Triggering actions
2) The table below presents the possible values for the action
parameter.
Possible action | Available filters |
---|---|
incoming_chat | chat_presence , only_my_chats |
chat_deactivated | chat_presence , only_my_chats |
chat_access_granted | chat_presence , only_my_chats |
chat_access_revoked | chat_presence , only_my_chats |
user_added_to_chat | chat_presence , only_my_chats |
user_removed_from_chat | chat_presence , only_my_chats |
incoming_event | chat_presence , author_type , only_my_chats |
event_updated | chat_presence , author_type , only_my_chats |
incoming_rich_message_postback | chat_presence , only_my_chats |
chat_properties_updated | chat_presence , only_my_chats |
chat_properties_deleted | chat_presence , only_my_chats |
thread_properties_updated | chat_presence , only_my_chats |
thread_properties_deleted | chat_presence , only_my_chats |
event_properties_updated | chat_presence , only_my_chats |
event_properties_deleted | chat_presence , only_my_chats |
thread_tagged | chat_presence , only_my_chats |
thread_untagged | chat_presence , only_my_chats |
routing_status_set | - |
agent_deleted | agent_ids |
incoming_customer | - |
customer_session_fields_updated | chat_presence |
events_marked_as_seen | chat_presence , only_my_chats |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/register_webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <your_username>:<your_PAT>' \
-d '{
"url": "http://myservice.com/webhooks",
"description": "Test webhook",
"action": "chat_deactivated",
"secret_key": "laudla991lamda0pnoaa0",
"owner_client_id": "asXdesldiAJSq9padj",
"type": "license"
}'
{
"id": "pqi8oasdjahuakndw9nsad9na"
}
List Webhooks
Lists all webhooks registered for the given Client ID.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_webhooks |
Required scopes | webhooks.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
owner_client_id | yes | string | The webhook owner (the Client ID for which the webhook is registered). |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"owner_client_id": "0805e283233042b37f460ed8fbf22160"
}'
[
{
"id": "pqi8oasdjahuakndw9nsad9na",
"url": "http://myservice.com/webhooks",
"description": "Test webhook",
"action": "chat_deactivated",
"filters": {
"chat_presence": {
"user_ids": {
"values": [
"johndoe@mail.com"
]
},
"my_bots": true
}
},
"owner_client_id": "asXdesldiAJSq9padj",
"type": "license"
}
]
Unregister Webhook
Unregisters a webhook previously registered for a Client ID (application).
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/unregister_webhook |
Required scopes | webhooks.configuration:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
id | Yes | string | Webhook ID |
owner_client_id | Yes | string | The webhook owner (the Client ID for which the webhook is registered). |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/unregister_webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your_access_token>' \
-d '{
"id": "pqi8oasdjahuakndw9nsad9na",
"owner_client_id": "0805e283233042b37f460ed8fbf22160"
}'
List Webhook Names
Lists all webhooks that are supported in a given API version. This method requires no authorization.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/list_webhook_names |
Required scopes | - |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
version | No | string | Defaults to the current stable API version |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/list_webhook_names \
-H 'Content-Type: application/json' \
-d '{
"version": "3.3"
}'
[
{
"action": "agent_deleted",
"filters": [
"agent_ids"
]
},
{
"action": "chat_access_granted",
"filters": [
"chat_presence",
"only_my_chats"
],
"additional_data": [
"chat_properties",
"chat_presence_user_ids"
]
},
{
"action": "incoming_customer"
}
]
Enable License Webhooks
Enables the disabled webhooks on the license.
Use this method only if you disabled the webhooks on the license via Disable License Webhooks. Otherwise, the webhooks will be automatically enabled when the associated application is installed on the license.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/enable_license_webhooks |
Required scopes | webhooks.state:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
owner_client_id | Yes | string | Required only when authorizing via PATs. The request will be rejected if you provide owner_client_id when authorizing with a Bearer Token. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/enable_license_webhooks \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Disable License Webhooks
Disables the webhooks on the license. The webhooks will stay disabled even after the associated application is reinstalled. To enable the webhooks again (and to rely on automatic webhooks enablement), use Enable License Webhooks.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/disable_license_webhooks |
Required scopes | webhooks.state:rw |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
owner_client_id | Yes | string | Required only when authorizing via PATs. The request will be rejected if you provide owner_client_id when authorizing with a Bearer Token. |
Response
No response payload (200 OK
).
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/disable_license_webhooks \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Get License Webhooks State
Gets the state of the webhooks registered for a given Client Id (application) on the license associated with the access token used in the request.
Specifics
Method URL | https://api.livechatinc.com/v3.3/configuration/action/get_license_webhooks_state |
Required scopes | webhooks.state:ro |
Request
Parameter | Required | Data type | Notes |
---|---|---|---|
owner_client_id | Yes | string | Required only when authorizing via PATs. The request will be rejected if you provide owner_client_id when authorizing with a Bearer Token. |
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.3/configuration/action/get_license_webhooks_state \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
{
"license_webhooks_enabled": true
}
Available webhooks
To see the list of available webhooks v3.3, visit the Webhooks document.
Possible errors
Error type | Default message | Description |
---|---|---|
authentication | Authentication error | An invalid or expired access token. |
authorization | Authorization error | User is not allowed to perform the action. |
already_exists | Already exists | It's impossible to create the resource as it already exists. |
group_not_found | Group not found | |
internal | Internal server error | |
license_expired | License expired | The end of license trial or subcription. |
limit_reached | Limit reached | Resource cannot be created/modified because the change would exceed the limit |
misdirected_request | Wrong region | Client's request should be performed to another region. The correct region is returned in the optional data object – this is where the client should be connected. |
not_found | Not found | The requested resource wasn't found. |
too_many_requests | Too many requests | The request's rate limit was exceeded. It'll be unblocked automatically after some time. |
transfer_ownership | Invalid transfer ownership request | Ownership cannot be transfered to this account (bot, suspended agent). |
unsupported_version | Cannot call unsupported API versions. | Unsupported protocol version. |
validation | Wrong format of request |
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@text.com. We'll be happy to hear from you!