API version

Configuration API

7 minutes reading time

Introduction

Configuration API is a service for storing configuration of license. You can set up here different types of features such as properties or webhooks.

Versioning

This document describes the Configuration API v3.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.

Run in Postman

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

Run in Postman

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 URLhttps://api.livechatinc.com/v3.2/configuration/action/create_agent
Required scopesaccounts--all:rc
Request
ParameterData typeRequiredNotes
idstringYesAgent ID
namestringYesAgent name
rolestringNoAgent role, should be one of the following: viceowner, administrator, normal (default).
avatar_pathstringNoURL path of the Agent's avatar
job_titlestringNoAgent's job title
mobilestringNoAgent's mobile number
max_chats_countintNoAgent's maximum number of concurrent chats
awaiting_approvalboolNoDetermines if the Agent will be awaiting approval after creation. Only a requester with the billing:rw scope can set this value to false.
groupsobject[]NoGroups an Agent belongs to.
groups[].iduintYesGroup ID; required only when group is included.
groups[].priority *stringYesAgent's priority in a group; required only when group is included.
notifications**string[]NoRepresents which Agent notifications are turned on.
email_subscriptions***string[]NoRepresents which subscriptions will be send to the Agent via email.
work_schedulerobjectNoWork scheduler options to set for the new Agent
work_scheduler.****.<work_scheduler>objectNo<work_scheduler> values *****

* Possible values for the groups[].priority parameter:

Possible valueNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. Corresponds to the Primary priority option in the LiveChat App.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. 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
Copied!
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"
        ]
      }'
Response
Copied!
{
	"id": "smith@example.com"
}

Get Agent

It returns the info about an Agent specified by id.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/get_agent
Required scopesagents--my:ro agents--all:ro
Request
Request objectTypeRequiredNotes
idstringYesAgent ID
fields*string[]NoAdditional fields to include.

* Possible values for the fields[] parameter:

Possible valueNotes
work_schedulerWork scheduler object for an Agent
groupsGroups an Agent belongs to
email_subscriptionsA list of an Agent's active subscriptions
notificationsA list of an Agent's enabled notifications
job_titleAgent's job title
mobileAgent's mobile number
max_chats_countAgent's maximum number of concurrent chats
suspendedBoolean value indicating if an Agent is suspended
awaiting_approvalBoolean value indicating if an Agent is awaiting approval
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"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 URLhttps://api.livechatinc.com/v3.2/configuration/action/list_agents
Required scopesagents--all:ro
Request
ParameterRequiredTypeNotes
filtersNoobjectPossible request filters
filters.group_idsNoint[]IDs of the groups from which you want to list Agents. You'll only get the Agents from the specified group(s).
fields*Nostring[]Additional Agent fields to include.

* Possible values for the fields[] parameter:

Possible valueNotes
groupsGroups an Agent belongs to
work_schedulerWork scheduler object for an Agent
email_subscriptionsA list of the Agent's active email subscriptions
notificationsA list of the Agent's enabled notifications
job_titleAgent's job title
mobileAgent's mobile number
max_chats_countAgent's maximum number of concurrent chats
suspendedBoolean value indicating if an Agent is suspended
awaiting_approvalBoolean value indicating if an Agent is awaiting approval
REQUEST
Copied!
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
          ]
        }
    }'
Response
Copied!
[
	{
		"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 URLhttps://api.livechatinc.com/v3.2/configuration/action/update_agent
Required scopesagents--my:rw agents--all:rw (to update other Agents within the same license)
Request
ParameterData typeRequiredNotes
idstringYesAgent ID
namestringNoAgent name
rolestringNoAgent role, should be one of the following: viceowner, administrator, normal
avatar_pathstringNoURL path for Agent avatar
job_titlestringNoAgent's job title
mobilestringNoAgent's mobile number
max_chats_countintNoAgent's maximum number of concurrent chats
groupsobject[]NoGroups an Agent belongs to.
groups[].iduintYesGroup ID; required only when group's included.
groups[].priority *stringYesAgent's priority in a group; required only when group's included.
notifications**string[]NoRepresents which Agent notifications are turned on.
email_subscriptions***string[]NoRepresents which subscriptions will be send to an Agent via email.
work_schedulerobjectNoWork scheduler options to set for a new Agent
work_scheduler.****.<work_scheduler>objectNo<work_scheduler> values *****

* Possible values for the groups[].priority parameter:

Possible valueNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. Corresponds to the Primary priority option in the LiveChat App.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. 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
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/delete_agent
Required scopesagents--all:rw
Request
ParameterRequiredData typeNotes
idYesstringAgent ID
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/suspend_agent
Required scopesagents--all:rw
Request
ParameterRequiredData typeNotes
idYesstringAgent ID
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/unsuspend_agent
Required scopesagents--all:rw billing:rw
Request
ParameterRequiredData typeNotes
idYesstringAgent ID
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/request_agent_unsuspension
Required scopes-
Request

Empty request payload.

Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/approve_agent
Required scopesagents-all:rw subscription_manage *

* subscription_manage is a private scope; it's not possible to configure it in Developer Console.

Request
ParameterRequiredData typeNotes
idYesstringAgent ID
Response

No response payload (200 OK).

REQUEST
Copied!
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 methodThe Bots API endpoint
POSThttps://api.livechatinc.com/v3.2/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Run in Postman

Create Bot

Creates a new Bot.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/create_bot
Required scopesagents-bot--my:rw
Request
ParameterRequiredData typeNotes
nameYesstringDisplay name
avatarNostringAvatar URL
max_chats_countNointMax. number of incoming chats that can be routed to the Bot; default: 6.
groupsNoobject[]Groups the Bot belongs to.
groups[].idNointGroup ID; required only when group's included.
groups[].priority *YesstringBot's priority in a group; required only when group's included.
webhooksNoobjectWebhooks sent to the Bot; for more info on possible values and payload, see Webhooks. Webhooks work only for online Bots.
webhooks.urlYesstringDestination URL for webhooks; required only when webhooks is included.
webhooks.secret_keyYesstringSecret sent in webhooks to verify webhook's source; required only when webhooks's included.
webhooks.actionsYesobject[]Triggering actions; required only when webhooks's included.
webhooks.actions[].nameYesstringThe name of the triggering action; required only when webhooks is included.
webhooks.actions[].filtersNoobjectFilters to check if a webhook should be triggered. For more info on filters, see Register webhook.
webhooks.actions[].additional_dataNostring[]Additional data that will arrive with webhooks.
work_schedulerNoobjectWork scheduler options to set for the new Bot. **
work_scheduler.***.<work_scheduler>Noobject<work_scheduler> values ****.

* Possible values for the groups[].priority parameter:

Possible valueNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. Corresponds to the Bot priority option in the LiveChat App.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. Corresponds to the Primary priority option in the LiveChat App.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. 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
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}

Delete Bot

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

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/update_bot
Required scopesagents-bot--my:rw agents-bot--all:rw (to update other Bots within the same license)
Request
ParameterRequiredData typeNotes
idYesstringBot ID
nameNostringDisplay name
avatarNostringAvatar URL
max_chats_countNointMaximum incoming chats that can be routed to the Bot.
groupsNoobject[]Groups the Bot belongs to
groups[].idYesuintGroup ID, required only when groups's present.
groups[].priority *YesstringBot's priority in the group; required only when groups is included.
default_group_priority **NostringThe default routing priority for a group without defined priority.
webhooksNoobjectWebhooks sent to the Bot. Webhooks work only for online Bots.
webhooks.urlYesstringDestination URL for webhooks; required only when webhooks is present.
webhooks.secret_keyYesstringSecret sent in webhooks to verify the webhook's source; required when webhooks is included.
webhooks.actionsYesobject[]Triggering actions; required only when webhooks is included.
webhooks.actions[].nameYesstringThe name of the triggering action; required only when webhooks is included.
webhooks.actions[].filtersNoobjectFilters to check if a webhook should be triggered. For more info on filters, see Register webhook.
webhooks.actions[].additional_dataNostring[]Additional data arriving with the webhook.
work_schedulerNoobjectWork scheduler options to set for the new Bot. ***
work_scheduler.****.<work_scheduler>Noobject<work_scheduler> values *.

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

Possible valuesNotes:
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents. Corresponds to the Bot priority option in the LiveChat App.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group. Corresponds to the Primary priority option in the LiveChat App.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group. Corresponds to the Secondary priority option in the LiveChat App.

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

Possible valuesNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group.
supervisorBot works as supervisor so it will not be assigned to any chats.

*** 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
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/list_bots
Required scopesagents-bot--my:ro agents-bot--all:ro
Request
ParameterRequiredTypeNotes
allNobooltrue - 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
Copied!
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
      }'
Response
Copied!
{
	"bot_agents": [
		{
			"id": "5c9871d5372c824cbf22d860a707a578",
			"name": "John Doe",
			"avatar": "https://example.com/avatar.jpg",
			"status": "accepting chats"
		}
	]
}

Get Bot

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/get_bot
Required scopesagents-bot--my:ro agents-bot--all:ro
Request
ParameterRequiredTypeNotes
bot_agent_idYesstringBot ID
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"bot_agent": {
		"id": "5c9871d5372c824cbf22d860a707a578",
		"name": "John Doe",
		"avatar": "https://example.com/avatar.jpg",
		"status": "accepting chats",
		"application": {
			"client_id": "asXdesldiAJSq9padj"
		},
		"max_chats_count": 6,
		"groups": [
			{
				"id": 0,
				"priority": "normal"
			},
			{
				"id": 1,
				"priority": "normal"
			},
			{
				"id": 2,
				"priority": "first"
			}
		],
		"webhooks": {
			"url": "http://myservice.com/webhooks",
			"secret_key": "JSauw0Aks8l-asAa",
			"actions": [
				{
					"name": "incoming_chat",
					"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 methodThe Groups API endpoint
POSThttps://api.livechatinc.com/v3.2/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Run in Postman

Create Group

Creates a new group.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/create_group
Required scopesgroups--all:rw
Request
Request objectData typeRequiredNotes
namestringYesGroup name (up to 180 chars)
language_codestringNoThe code of the group languange
agent_priorities*objectYesAgents' 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 valueNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group.
REQUEST
Copied!
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"
        }
      }'
Response
Copied!
{
	"id": 19
}

Update Group

Updates an existing group.

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/update_group
Required scopesgroups--my:rw groups--all:rw (to update groups the requester is not a member of)
Request
Request objectData typeRequiredNotes
idintYesGroup ID
namestringNoGroup name (up to 180 chars)
language_codestringNoThe code of the group languange
agent_priorities*objectNoAgents' 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 valueNotes
firstThe highest chat routing priority. Agents with the first priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
normalThe medium chat routing priority. Agents with the normal priority get chats before those with the last priority, when there are no Agents with the first priority available with free slots in the group.
lastThe lowest chat routing priority. Agents with the last priority get chats when there are no Agents with the first or normal priority available with free slots in the group.
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/delete_group
Required scopesgroups--my:rw groups--all:rw (to delete groups the requester is not a member of)
Request
Request objectData typeRequiredNotes
idintYesGroup ID
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/list_groups
Required scopesgroups--all:ro
Request
Request objectData typeRequiredNotes
fields*string[]NoAdditional fields to include.

* Possible values for the fields[] parameter:

Possible valueNotes
agent_prioritiesAn object containing Agents belonging to a group, along with their priorities.
routing_statusThe routing status of a group.
REQUEST
Copied!
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 '{}'
Response
Copied!
[
	{
		"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 URLhttps://api.livechatinc.com/v3.2/configuration/action/get_group
Required scopesgroups--my:ro groups--all:ro (to get groups the requester is not a member of)
Request
Request objectData typeRequiredNotes
idintYesGroup ID
fields*string[]NoAdditional fields to include.

* Possible values for the fields[] parameter:

Possible valueNotes
agent_prioritiesAn object containing Agents belonging to a group, along with their priorities.
routing_statusThe routing status of a group.
REQUEST
Copied!
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"]
      }'
Response
Copied!
{
	"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 to 3).

Test properties

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

NamespacePropertyTypeAccess
testbool_propertyboolrw for everyone everywhere
testint_propertyintrw for everyone everywhere
teststring_propertystringrw for everyone everywhere
testtokenized_string_propertytokenized_stringrw for everyone everywhere

The tokenized_string property is similar to the string type. The values of a tokenized_string are split in tokens to enable searching for each word separately.

The general properties format
Copied!
{
    "properties": {
        "<namespace>": {
            "<property_name>": "<property_value>",
            "<property_name>": "<property_value>"
        }
    }
}

Methods

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

Run in Postman

Register Properties

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

*) Only one domain and one range can be set for a single property.

Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://api.livechatinc.com/v3.2/configuration/action/list_registered_properties
Required scopesproperties--my:ro properties--all:ro (to list properties in all namespaces)
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, it returns all properties within a given license; default: false.
REQUEST
Copied!
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 '{}'
Response
Copied!
{
	"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 URLhttps://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
ParameterRequiredData typeNotes
propertiesYesobjectAn object with namespaces as keys and properties (grouped in objects) as values.
Response

No response payload (200 OK).

REQUEST
Copied!
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"
              }
          }
      }'
Response
Copied!
{}

List License Properties

Returns the properties set within a license.

Specifics
Method URLhttps://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
ParameterRequiredData typeNotes
namespace_prefixNostringProperties namespace prefix
name_prefixNostringProperties name prefix
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"0805e283233042b37f460ed8fbf22160": {
		"string_property": "string value"
	}
}

Delete License Properties

Deletes the properties set within a license.

Specifics
Method URLhttps://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
ParameterRequiredData typeNotes
propertiesYesobjectAn object with namespaces as keys and property_names (in an array) as values.
Response

No response payload (200 OK).

REQUEST
Copied!
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 URLhttps://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
ParameterRequiredData typeNotes
group_idYesnumberID of the group you set the properties for.
propertiesYesobjectAn object with namespaces as keys and properties (grouped in objects) as values.
Response

No response payload (200 OK).

REQUEST
Copied!
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"
              }
          }
      }'
Response
Copied!
{}

List Group Properties

Returns the properties set within a group.

Specifics
Method URLhttps://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
ParameterRequiredData typeNotes
group_idYesnumberID of the group you retrieve properties from.
namespace_prefixNostringProperties namespace prefix
name_prefixNostringProperties name prefix
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"0805e283233042b37f460ed8fbf22160": {
		"string_property": "group property value"
	}
}

Delete Group Properties

Deletes the properties set within a group.

Specifics
Method URLhttps://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
ParameterRequiredData typeNotes
group_idYesnumberID of the group you delete properties from.
propertiesYesobjectAn object with namespaces as keys and property_names (in an array) as values.
Response

No response payload (200 OK).

REQUEST
Copied!
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"]
          }
      }'
general webhook format
Copied!
{
  "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
Actionincoming_chat
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
chatChat data structure
Sample webhook
Copied!
{
  "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
Actionchat_deactivated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_idMissing if a thread was closed by the router.
Sample webhook
Copied!
{
  "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
Actionchat_access_granted
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
idChat id
Sample webhook
Copied!
{
  "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
Actionchat_access_revoked
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
idChat Id
Sample webhook
Copied!
{
  "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_access_set

Informs that new, single access to a chat was set. The existing access is overwritten.

Specifics
Actionchat_access_set
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
idChat id
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_access_set",
  "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
Actionuser_added_to_chat
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_typePossible values: agent, customer
Sample webhook
Copied!
{
  "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
Actionuser_removed_from_chat
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
user_typePossible values: agent, customer
Sample webhook
Copied!
{
  "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
Actionincoming_event
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "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
Actionevent_updated
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "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
Actionincoming_rich_message_postback
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "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
Actionchat_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionchat_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionthread_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionthread_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionevent_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesThis is not a full properties object. This webhook shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionevent_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
ObjectNotes
propertiesThis is not a full properties object. This webhook shows only the properties that have been recently updated.
Sample webhook
Copied!
{
  "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
Actionthread_tagged
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "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
Actionthread_untagged
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "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
Actionrouting_status_set
Push equivalent inAgent Chat API
Webhook payload
ObjectNotes
statusPossible values: accepting chats, not accepting chats, offline (for Bots only)
Sample webhook
Copied!
{
  "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
Actionagent_deleted
Push equivalent in-
Sample webhook
Copied!
{
  "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
Actioncustomer_created
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "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
Actionevents_marked_as_seen
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "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 methodThe Webhooks API endpoint
POSThttps://api.livechatinc.com/v3.2/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Run in Postman

Register Webhook

Specifics
Method URLhttps://api.livechatinc.com/v3.2/configuration/action/register_webhook
Required scopeswebhooks--my:rw
Request objectRequiredData typeNotes
action*yesstringThe action that triggers sending a webhook.
secret_keyyesstringThe secret key sent in webhooks to verify the source of a webhook.
urlyesstringDestination URL for the webhook
additional_datano[]stringAdditional data arriving with the webhook. Value: chat properties (all actions except for agent_status_changed, agent_deleted, customer_created)
descriptionnostringWebhook description
filtersnoobjectFilters to check if a webhook should be triggered.
filters.author_typenostringPossible values: customer, agent; allowed only for the incoming_event and event_updated actions.
filters.only_my_chatsnobooltrue or false; triggers webhooks only for chats with the property source.client_id set to my client_id.
filters.chat_member_idsnoobjectOnly one filter (agents_any or agents_exclude) is allowed.
filters.chat_member_ids.agents_anyno[]stringArray of Agents' ids; if any specified Agent is in the chat, the webhook will be triggered.
filters.chat_member_ids.agents_excludeno[]stringArray of Agents' ids; If any specified Agent is in the chat, the webhook will not be triggered.
Triggering actions

* The table below presents the possible values for the action parameter.

Possible actionAvailable filters
incoming_chatchat_member_ids, only_my_chats
chat_deactivatedchat_member_ids, only_my_chats
chat_access_grantedchat_member_ids, only_my_chats
chat_access_revokedchat_member_ids, only_my_chats
chat_access_setchat_member_ids, only_my_chats
user_added_to_chatchat_member_ids, only_my_chats
user_removed_from_chatchat_member_ids, only_my_chats
incoming_eventchat_member_ids, author_type, only_my_chats
event_updatedchat_member_ids, author_type, only_my_chats
incoming_rich_message_postbackchat_member_ids, only_my_chats
chat_properties_updatedchat_member_ids, only_my_chats
chat_properties_deletedchat_member_ids, only_my_chats
thread_properties_updatedchat_member_ids, only_my_chats
thread_properties_deletedchat_member_ids, only_my_chats
event_properties_updatedchat_member_ids, only_my_chats
event_properties_deletedchat_member_ids, only_my_chats
thread_taggedchat_member_ids, only_my_chats
thread_untaggedchat_member_ids, only_my_chats
routing_status_set-
agent_deletedchat_member_ids, agent_ids
customer_created-
events_marked_as_seenchat_member_ids, only_my_chats
REQUEST
Copied!
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"
      }'
Response
Copied!
{
	"webhook_id": "pqi8oasdjahuakndw9nsad9na"
}

List Registered Webhooks

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

No response payload (200 OK).

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