Configuration API

Introduction

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

Versioning

This document describes the Configuration API v3.2. This is the deprecated version. We encourage you to migrate to the latest 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.2 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace the sample token with your own.

Agents

An agent is a type of user who communicates with customers. 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.2/configuration/action/<action>`

Required header	Value
`Content-Type`	`application/json`

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

Create Agent

Creates a new agent with specified parameters within a license.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/create_agent`
Required scopes	`accounts--all:rc` `accounts--all:rw`¹ `subscription.lc:rw`¹ ² `accounts.roles.lc--all:rw`³

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` ⁴	`string`	Yes	Agent's priority in a group; required only when `group` is included.
`notifications`⁵	`string[]`	No	Represents which Agent notifications are turned on.
`email_subscriptions`⁶	`string[]`	No	Represents which subscriptions will be send to the Agent via email.
`work_scheduler`	`object`	No	Work scheduler options to set for the new Agent
`work_scheduler.****.<work_scheduler>`	`object`	No	`<work_scheduler>` values⁷

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

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/get_agent`
Required scopes	`agents--my:ro` `agents--all:ro`

Request

Parameter	Type	Required	Notes
`id`	`string`	Yes	Agent ID
`fields`¹	`string[]`	No	Additional fields to include.

1) Possible values for the fields[] parameter:

Possible value	Notes
`work_scheduler`²	Work scheduler object for an Agent
`groups`	Groups an Agent belongs to
`email_subscriptions`	A list of an Agent's active subscriptions
`notifications`	A list of an Agent's enabled notifications
`job_title`	Agent's job title
`mobile`	Agent's mobile number
`max_chats_count`	Agent's maximum number of concurrent chats
`suspended`	Boolean value indicating if an Agent is suspended
`awaiting_approval`	Boolean value indicating if an Agent is awaiting approval

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_agents`
Required scopes	`agents--all:ro`

Request

Parameter	Required	Type	Notes
`filters`	No	`object`	Possible request filters
`filters.group_ids`	No	`int[]`	IDs of the groups from which you want to list Agents. You'll only get the Agents from the specified group(s).
`fields`¹	No	`string[]`	Additional Agent fields to include.

1) Possible values for the fields[] parameter:

Possible value	Notes
`groups`	Groups an Agent belongs to
`work_scheduler`²	Work scheduler object for an Agent
`email_subscriptions`	A list of the Agent's active email subscriptions
`notifications`	A list of the Agent's enabled notifications
`job_title`	Agent's job title
`mobile`	Agent's mobile number
`max_chats_count`	Agent's maximum number of concurrent chats
`suspended`	Boolean value indicating if an Agent is suspended
`awaiting_approval`	Boolean value indicating if an Agent is awaiting approval

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/update_agent`
Required scopes	`agents--my:rw` `agents--all:rw`¹ `accounts.roles.lc--all:rw`²

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` ³	`string`	Yes	Agent's priority in a group; required only when `group`'s included.
`notifications`⁴	`string[]`	No	Represents which Agent notifications are turned on.
`email_subscriptions`⁵	`string[]`	No	Represents which subscriptions will be send to an Agent via email.
`work_scheduler`	`object`	No	Work scheduler options to set for a new Agent
`work_scheduler.****.<work_scheduler>`	`object`	No	`<work_scheduler>` values ⁶

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

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/delete_agent`
Required scopes	`agents--my:rw` `accounts--my:rw` `agents--all:rw` ¹ `accounts--all:rw` ¹

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

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.

❗️ 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.2/configuration/action/suspend_agent`
Required scopes	`agents--all:rw` `sessions--all:rw`¹

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/unsuspend_agent`
Required scopes	`agents--all:rw` `accounts--all:rw` `subscription.lc:rw`¹

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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/request_agent_unsuspension`
Required scopes	-

Request

Empty request payload.

Response

No response payload (200 OK).

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/approve_agent`
Required scopes	`agents--all:rw` `accounts--all:rw` `subscription.lc:rw` ¹

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

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 method	The Bots API endpoint
`POST`	`https://api.livechatinc.com/v3.2/configuration/action/<action>`

Required header	Value
`Content-Type`	`application/json`

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

Create Bot

Creates a new Bot.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/create_bot`
Required scopes	`agents-bot--my:rw`

Request

Parameter	Required	Data type	Notes
`name`	Yes	`string`	Display name
`avatar`	No	`string`	Avatar URL
`max_chats_count`	No	`int`	Max. number of incoming chats that can be routed to the Bot; default: 6. Limited to 500.
`default_group_priority` ⁵	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` ¹	Yes	`string`	Bot's priority in a group; required only when `group`'s included.
`webhooks`	No	`object`	Webhooks sent to the Bot; for more info on possible values and payload, see Webhooks. Webhooks work only for online Bots.
`webhooks.url`	Yes	`string`	Destination URL for webhooks; required only when `webhooks` is included.
`webhooks.secret_key`	Yes	`string`	Secret sent in webhooks to verify webhook's source; required only when `webhooks`'s included.
`webhooks.actions`	Yes	`object[]`	Triggering actions; required only when `webhooks`'s included. Actions have to be unique.
`webhooks.actions[].name`	Yes	`string`	The name of the triggering action; required only when `webhooks` is included.
`webhooks.actions[].filters`	No	`object`	Filters to check if a webhook should be triggered. For more info on filters, see Register webhook.
`webhooks.actions[].additional_data`	No	`string[]`	Additional data that will arrive with webhooks.
`work_scheduler`	No	`object`	Work scheduler options to set for the new Bot. ²
`work_scheduler.***.<work_scheduler>`	No	`object`	`<work_scheduler>` values ⁴.

1) Possible values for the groups[].priority parameter:

Possible value	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) 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

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

5) 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.

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

Deletes a bot specified by id.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/delete_bot`
Required scopes	`agents-bot--my:rw` `agents-bot--all:rw`

Request

Parameter	Required	Type	Notes
`bot_agent_id`	Yes	`string`	Bot ID

Response

No response payload (200 OK).

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/update_bot`
Required scopes	`agents-bot--my:rw` `agents-bot--all:rw` (to update other Bots within the same license)

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Bot ID
`name`	No	`string`	Display name
`avatar`	No	`string`	Avatar URL
`max_chats_count`	No	`int`	Maximum incoming chats that can be routed to the Bot. 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` ¹	Yes	`string`	Bot's priority in the group; required only when `groups` is included.
`default_group_priority` ²	No	`string`	The default routing priority for a group without defined priority.
`webhooks`	No	`object`	Webhooks sent to the Bot. Webhooks work only for online Bots.
`webhooks.url`	Yes	`string`	Destination URL for webhooks; required only when `webhooks` is present.
`webhooks.secret_key`	Yes	`string`	Secret sent in webhooks to verify the webhook's source; required when `webhooks` is included.
`webhooks.actions`	Yes	`object[]`	Triggering actions; required only when `webhooks` is included.
`webhooks.actions[].name`	Yes	`string`	The name of the triggering action; required only when `webhooks` is included.
`webhooks.actions[].filters`	No	`object`	Filters to check if a webhook should be triggered. For more info on filters, see Register webhook.
`webhooks.actions[].additional_data`	No	`string[]`	Additional data arriving with the webhook.
`work_scheduler`	No	`object`	Work scheduler options to set for the new Bot. ³
`work_scheduler.****.<work_scheduler>`	No	`object`	`<work_scheduler>` values ⁵.

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.

3) 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

5) <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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_bots`
Required scopes	`agents-bot--my:ro` `agents-bot--all:ro`

Request

Parameter	Required	Type	Notes
`all`	No	`bool`	`true` - gets all Bots within a license. `false` (default)¹ - returns only the requester's Bots.

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.

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

It returns the info about a bot with a given id.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/get_bot`
Required scopes	`agents-bot--my:ro` `agents-bot--all:ro`

Request

Parameter	Required	Type	Notes
`bot_agent_id`	Yes	`string`	Bot ID

REQUEST

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 method	The Groups API endpoint
`POST`	`https://api.livechatinc.com/v3.2/configuration/action/<action>`

Required header	Value
`Content-Type`	`application/json`

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

Create Group

Creates a new group.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/create_group`
Required scopes	`groups--all:rw`

Request

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`¹	`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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/update_group`
Required scopes	`groups--my:rw` `groups--all:rw` (to update groups the requester is not a member of)

Request

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`¹	`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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/delete_group`
Required scopes	`groups--my:rw` `groups--all:rw` (to delete groups the requester is not a member of)

Request

Parameter	Data type	Required	Notes
`id`	`int`	Yes	Group 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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_groups`
Required scopes	`groups--all:ro`

Request

Parameter	Data type	Required	Notes
`fields`¹	`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

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/get_group`
Required scopes	`groups--my:ro` `groups--all:ro` (to get groups the requester is not a member of)

Request

Parameter	Data type	Required	Notes
`id`	`int`	Yes	Group ID
`fields`¹	`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

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.

Namespace	Property	Type	Access
`test`	`bool_property`	`bool`	rw for everyone everywhere
`test`	`int_property`	`int`	rw for everyone everywhere
`test`	`string_property`	`string`	rw for everyone everywhere
`test`	`tokenized_string_property`	`tokenized_string`	rw for everyone everywhere

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

The general properties format

Copied!

{
    "properties": {
        "<namespace>": {
            "<property_name>": "<property_value>",
            "<property_name>": "<property_value>"
        }
    }
}

Methods

HTTP method	The Properties API endpoint
`POST`	`https://api.livechatinc.com/v3.2/configuration/action/<action>`

Required header	Value
`Content-Type`	`application/json`

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

Register Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/register_properties`
Required scopes	`properties--my:rw`(to create my properties in my namespace)

Request

Parameter	Required	Data type	Notes
`<property_name>.type`	Yes	`string`	Possible values: `int`, `string`, `bool`, and `tokenized_string`
`<property_name>.locations`	Yes	`object`
`<property_name>.locations.<location>`	min. one `location`	`object`	Possible values: `chat`, `thread`, `event`, `license`, `group`
`<property_name>.locations.<location>.access.<user>`	min. one `user`	`object`	Possible values: `agent`, `customer`
`<property_name>.locations.<location>.access.<user>.read`	Yes	`bool`	If set to `true`, then `<user>` can read this property.
`<property_name>.locations.<location>.access.<user>.write`	Yes	`bool`	If set to `true`, then `<user>` can write to this property.
`<property_name>.description`	No	`string`	Property description
`<property_name>.domain` ¹	No	`[<type>]`	Array of values that properties can be set to.
`<property_name>.range` ¹	No	`object`	Range of values that properties can be set to.
`<property_name>.range.from`	No	`int`	Only values equal or greater than this parameter can be set to this property.
`<property_name>.range.to`	No	`int`	Only values equal or lower than this parameter can be set to this property.

1) 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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_registered_properties`
Required scopes	`properties--my:ro` `properties--all:ro` (to list properties in all namespaces)

Request

Parameter	Required	Data type	Notes
`all`	No	`bool`	If set to `true`, it returns all properties within a given license; default: `false`.

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/update_license_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, setting license properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write.

Request

Parameter	Required	Data type	Notes
`properties`	Yes	`object`	An object with namespaces as keys and properties (grouped in objects) as values.

Response

No response payload (200 OK).

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_license_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, retrieving license properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.read.

Request

Parameter	Required	Data type	Notes
`namespace_prefix`	No	`string`	Properties namespace prefix
`name_prefix`	No	`string`	Properties name prefix

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/delete_license_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, deleting license properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write.

Request

Parameter	Required	Data type	Notes
`properties`	Yes	`object`	An object with namespaces as keys and property_names (in an array) as values.

Response

No response payload (200 OK).

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/update_group_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, setting group properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write.

Request

Parameter	Required	Data type	Notes
`group_id`	Yes	`number`	ID of the group you set the properties for.
`properties`	Yes	`object`	An object with namespaces as keys and properties (grouped in objects) as values.

Response

No response payload (200 OK).

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_group_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, retrieving group properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.read.

Request

Parameter	Required	Data type	Notes
`group_id`	Yes	`number`	ID of the group you retrieve properties from.
`namespace_prefix`	No	`string`	Properties namespace prefix
`name_prefix`	No	`string`	Properties name prefix

REQUEST

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 URL	`https://api.livechatinc.com/v3.2/configuration/action/delete_group_properties`
Required scopes¹	-

1) If the requester's Client ID matches the namespace, deleting group properties is always allowed. Otherwise, the permission depends on how the property was configured during registration; parameter: <property_name>.locations.<location>.access.<user>.write.

Request

Parameter	Required	Data type	Notes
`group_id`	Yes	`number`	ID of the group you delete properties from.
`properties`	Yes	`object`	An object with namespaces as keys and property_names (in an array) as values.

Response

No response payload (200 OK).

REQUEST

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"]
          }
      }'

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.

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
    }
  }
}

Methods

HTTP method	The Webhooks API endpoint
`POST`	`https://api.livechatinc.com/v3.2/configuration/action/<action>`

Required header	Value
`Content-Type`	`application/json`

Response Header	Value	Notes
`Legacy`	`YYYY-MM-DD`	The date when the `legacy` stage ends.
`Deprecation`	`YYYY-MM-DD`	The date when the `deprecated` stage ends.

Register Webhook

The number of webhooks that you can register is limited and depends on the authorization method:

When using PATs: 10 for every action. Using multiple PATs doesn't rise the limit.
When using Bearer Tokens: 60 for every action.

Specifics


Method URL	`https://api.livechatinc.com/v3.2/configuration/action/register_webhook`
Required scopes	`webhooks--my:rw`

Parameter	Required	Data type	Notes
`action`¹	yes	`string`	The action that triggers sending a webhook.
`secret_key`	yes	`string`	The secret key sent in webhooks to verify the source of a webhook.
`url`	yes	`string`	Destination URL for the webhook
`additional_data`	no	`[]string`	Additional data arriving with the webhook. Value: `chat_properties` (all actions except for `agent_status_changed`, `agent_deleted`, `customer_created`)
`description`	no	`string`	Webhook description
`filters`	no	`object`	Filters to check if a webhook should be triggered.
`filters.author_type`	no	`string`	Possible values: `customer`, `agent`; allowed only for the `incoming_event` and `event_updated` actions.
`filters.only_my_chats`	no	`bool`	`true` or `false`; triggers webhooks only for chats with the property `source.client_id` set to my `client_id`.
`filters.chat_member_ids`	no	`object`	Only one filter (`agents_any` or `agents_exclude`) is allowed.
`filters.chat_member_ids.agents_any`	no	`[]string`	Array of Agents' ids; if any specified Agent is in the chat, the webhook will be triggered.
`filters.chat_member_ids.agents_exclude`	no	`[]string`	Array of Agents' ids; If any specified Agent is in the chat, the webhook will not be triggered.

Triggering actions

1) The table below presents the possible values for the action parameter.

Possible action	Available filters
`incoming_chat`	`chat_member_ids`, `only_my_chats`
`chat_deactivated`	`chat_member_ids`, `only_my_chats`
`chat_access_granted`	`chat_member_ids`, `only_my_chats`
`chat_access_revoked`	`chat_member_ids`, `only_my_chats`
`user_added_to_chat`	`chat_member_ids`, `only_my_chats`
`user_removed_from_chat`	`chat_member_ids`, `only_my_chats`
`incoming_event`	`chat_member_ids`, `author_type`, `only_my_chats`
`event_updated`	`chat_member_ids`, `author_type`, `only_my_chats`
`incoming_rich_message_postback`	`chat_member_ids`, `only_my_chats`
`chat_properties_updated`	`chat_member_ids`, `only_my_chats`
`chat_properties_deleted`	`chat_member_ids`, `only_my_chats`
`thread_properties_updated`	`chat_member_ids`, `only_my_chats`
`thread_properties_deleted`	`chat_member_ids`, `only_my_chats`
`event_properties_updated`	`chat_member_ids`, `only_my_chats`
`event_properties_deleted`	`chat_member_ids`, `only_my_chats`
`thread_tagged`	`chat_member_ids`, `only_my_chats`
`thread_untagged`	`chat_member_ids`, `only_my_chats`
`routing_status_set`	-
`agent_deleted`	`agent_ids`
`customer_created`	-
`events_marked_as_seen`	`chat_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 URL	`https://api.livechatinc.com/v3.2/configuration/action/list_registered_webhooks`
Required scopes	`webhooks--my:ro` `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 URL	`https://api.livechatinc.com/v3.2/configuration/action/unregister_webhook`
Required scopes	`webhooks--my:rw` `webhooks--all:rw`

Request

Parameter	Required	Data type	Notes
`webhook_id`	Yes	`string`	Webhook ID

Response

No response payload (200 OK).

REQUEST

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"
      }'

Available webhooks

To see the list of available webhooks v3.2, 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_exist`	Already exist	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`	Resource 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`	Transfer ownership	Ownership cannot be transfered to this account (bot, suspended agent).
`unsupported_version`	Unsupported version	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!

Configuration API.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

Versioning

Lifecycle headers

Authentication

Data centers

Propagation delay

Postman Collection

Agents

Methods

Create Agent

Specifics

Request

Get Agent

Specifics

Request

List Agents

Specifics

Request

Update Agent

Specifics

Request

Response

Delete Agent

Specifics

Request

Response

Suspend Agent

Specifics

Request

Response

Unsuspend Agent

Specifics

Request

Response

Request Agent Unsuspension

Specifics

Request

Response

Approve Agent

Specifics

Request

Response

Bots

Methods

Create Bot

Specifics

Request

Delete Bot

Specifics

Request

Response

Update Bot

Specifics

Request

Response

List Bots

Specifics

Request

Get Bot

Specifics

Request

Groups

Methods

Create Group

Specifics

Request

Update Group

Specifics

Request

Response

Delete Group

Specifics

Request

Response

List Groups

Specifics

Request

Get Group

Specifics

Request

Configuration API