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.1. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...

Authentication for Configuration API is handled by access tokens. Find out how to get an access token from Agent authorization flows. If a method requires particular authorization scopes, you’ll find them included in the method description. Each request should contain the Authorization: Bearer <your_access_token> header.

Data centers

LiveChat system operates in two data centers: dal (USA) and fra (Europe). The default data center is dal.

All the LiveChat OAuth2.0 access tokens have a prefix: dal- or fra-. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.

Summing up, if the user token starts with fra-, you should add the X-Region: fra header. If the token starts with dal-, you don’t have to specify the header.

Propagation delay

All configurations set by this API will have action in system after max 2 minutes. This delay will be removed in the future.

Postman Collection

You can find all the requests from the Configuration API v3.1 in Postman. In our collection, we use environment variables for the API version and the access token. Importing the collection from the link below downloads the LiveChat Web API environment as well. Remember to replace the sample token with your own.

Bot Agents

Bot Agents enables writing integrations using the Agent Chat API - both RTM and Web - to communicate in chats as regular Agents. A Bot Agent shares the SSO access token with the Agent who created the Bot. Each Bot Agent is a resource owned by an application in Developers Platform, identified by its own client_id.

Unlike Agents, Bot Agents don't have passwords or emails - you cannot log in as a Bot.

Methods

HTTP method	The Bot Agents API endpoint
`POST`	`https://api.livechatinc.com/v3.1/configuration/action/<action>`

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

Create Bot Agent

Specifics


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

Request

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

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

Possible value	Notes
`accepting chats`	Agent is logged in. The chat router routes incoming chats to the Agent.
`not accepting chats`	Agent is logged in, but the chat router doesn't route incoming chats to the Agent.
`offline`	Agent isn't logged in.

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

Possible value	Notes
`first`	The highest chat routing priority. Agents with the `first` priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
`normal`	The medium chat routing priority. Agents with the `normal` priority get chats before those with the `last` priority, when there are no Agents with the `first` priority available with free slots in the group.
`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.

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

Possible values	Notes
`first`	The highest chat routing priority. Agents with the `first` priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
`normal`	The medium chat routing priority. Agents with the `normal` priority get chats before those with the `last` priority, when there are no Agents with the `first` priority available with free slots in the group.
`last`	The lowest chat routing priority. Agents with the `last` priority get chats when there are no Agents with the `first` or `normal` priority available with free slots in the group.
`supervisor`	Agents with the `supervisor` priority will not get any chats assigned automatically.

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/create_bot_agent \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Bot Name",
      "status": "accepting chats"
      }'

Response

Copied!

{
    "bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
}

Remove Bot Agent

Specifics


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

Request

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/remove_bot_agent \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "bot_agent_id": "505591fc9fc2d6e92798bed7d9d8f079"
      }'

Update Bot Agent

Specifics


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

Request

Parameter	Required	Data type	Notes
`id`	Yes	`string`	Bot Agent ID
`name`	No	`string`	Display name
`avatar`	No	`string`	Avatar URL
`status` *	No	`string`	Agent status
`max_chats_count`	No	`int`	Maximum incoming chats that can be routed to an Agent. Limited to 500.
`groups`	No	`object[]`	Groups an Agent belongs to
`groups[].id`	Yes	`uint`	Group ID, required only when `groups`'s present.
`groups[].priority` **	Yes	`string`	Agent'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 an Agent. 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.

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

Possible values	Notes
`accepting chats`	Agent is logged in. The chat router routes incoming chats to the Agent.
`not accepting chats`	Agent is logged in, but the chat router doesn't route incoming chats to the Agent.
`offline`	Agent isn't logged in.

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

Possible values	Notes:
`first`	The highest chat routing priority. Agents with the `first` priority get chats before others from the same group, e.g. Bots can get chats before regular Agents.
`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.

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

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/update_bot_agent \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": "ce54714e3d2b53adbfff09dbdbdd56e9",
      "name": "New Bot Name"
      }'

Get Bot Agents

Specifics


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

Request

Parameter	Required	Type	Notes
`all`	No	`bool`	Get all Bot Agents, if `false` returns only caller's Bot Agents, default value is `false`

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/get_bot_agents \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "all": false
        }'

Response

Copied!

{
    "bot_agents": [{
        "id": "5c9871d5372c824cbf22d860a707a578",
        "name": "John Doe",
        "avatar": "https://example.com/avatar.jpg",
        "status": "accepting chats"
    }]
}

Get Bot Agent Details

Specifics


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

Request

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

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/get_bot_agent_details \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "bot_agent_id": "5c9871d5372c824cbf22d860a707a578"
        }'

Response

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_thread",
                "filters": {
                  "chat_properties": {
                     "source": {
                        "type": {
                           "values": ["facebook", "twitter"]
                        }
                      }
                  }
                }
            },{
                "name": "incoming_event",
                "additional_data": ["chat_properties"]
            }]
        }
    }
}

Properties

Properties are key-value storages. They can be set within a chat, a thread, or an event.

You can create properties within a license and configure them using the Configuration API. Properties are grouped in namespaces, which helps distinguishing which property belongs to a given integration. Your namespace is always named after your Client Id.

You can configure the property type, location, and domain.

Property types

There are four property types:

int (int32)
bool
string
tokenized_string

The tokenized_string type is a string split to tokens before indexing in our search engine. It can be useful for longer strings, such as messages. It should not be used for keywords.

Property locations

Properties can be set for the following locations:

chat
thread
event

You can configure access to properties within those locations. For example, you could create a property visible only to agents in a chat and thread, but not in an event.

Property domain

The property domain is a set of values that a property can be assigned to.

Property domain can be configured in two ways:

by defining a set of values explicitly allowed in this property (for example [1, 2, 3]).
by defining a range. All values within the range are allowed in this property. It works only for numeric types (for example a range from 1 to 3).

Test properties

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

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.1/configuration/action/<action>`

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

Create Properties

Specifics


Method URL	`https://api.livechatinc.com/v3.1/configuration/action/create_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`
`<property_name>.locations.<location>.access.<user>`	min. one `user`	`object`	Possible values: `agent`, `customer`
`<property_name>.locations.<location>.access.<user>.read`	Yes	`bool`	If set to `true`, then `<user>` can read this property.
`<property_name>.locations.<location>.access.<user>.write`	Yes	`bool`	If set to `true`, then `<user>` can write to this property.
`<property_name>.description`	No	`string`	Property description
`<property_name>.domain` *	No	`[<type>]`	Array of values that properties can be set to.
`<property_name>.range` *	No	`object`	Range of values that properties can be set to.
`<property_name>.range.from`	No	`int`	Only values equal or greater than this parameter can be set to this property.
`<property_name>.range.to`	No	`int`	Only values equal or lower than this parameter can be set to this property.

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

Response

No response payload (200 OK).

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/create_properties \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "score": {
        "type": "int",
        "locations": {
            "chat": {
                "access": {
                    "agent": {
                        "read": true,
                        "write": true
                    },
                    "customer": {
                        "read": true,
                        "write": true
                    }
                }
            }
        }
    },
    "comment": {
        "type": "string",
        "locations": {
            "chat": {
                "access": {
                    "agent": {
                        "read": true,
                        "write": true
                    },
                    "customer": {
                        "read": true,
                        "write": true
                    }
                }
            }
        }
    }
}'

Get Property Configs

Specifics


Method URL	`https://api.livechatinc.com/v3.1/configuration/action/get_property_configs`
Required scopes	`properties--my:ro` `properties--all:ro` (to create 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.1/configuration/action/get_property_configs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'

Response

Copied!

{
    "58737b5829e65621a45d598aa6f2ed8e":{
    "greeting":{
    "type":"string",
    "locations":{
      "chat":{
        "access":{
          "agent":{
            "read":true,
            "write":false
          },
          "customer":{
            "read":true,
            "write":true
          }
        }
      }
    },
    "domain": ["hello", "hi"]
  },
  "scoring":{
    "type":"int",
    "locations":{
      "event":{
        "access":{
          "agent":{
            "read":true,
            "write":true
          }
        }
      }
    },
    "range": {
      "from": 0,
      "to": 10
    }

        }
    }
}

Webhooks

Here's what you need to know about webhooks:

Webhooks notify you when specific events occur.
They can be generated by both Web and RTM API actions.
To receive webhooks, you need to register them first.

When your server receives a webhook from LiveChat, it should respond with HTTP 200 response. Otherwise, LiveChat will retry sending the webhook to your service a number of times until it receives the correct HTTP 200 response.

The timeout is set to ~10 seconds. If we don't receive HTTP 200 response within that time period, we'll retry sending the webhook up to 10 times within 6 hours.

general webhook format

Copied!

{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "<action>",
  "payload": {
    },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Methods

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

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

Register Webhook

Specifics


Method URL	`https://api.livechatinc.com/v3.1/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 that will arrive with the webhook.
`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 `incoming_event` and `event_updated` actions.
`filters.only_my_chats`	No	`bool`	`true` or `false`; triggers webhooks only for chats with the property `source.client_id` set to my `client_id`.
`filters.chat_member_ids`	No	`object`	Only one filter (`agents_any` or `agents_exclude`) is allowed.
`filters.chat_member_ids.agents_any`	No	`[]string`	Array of Agents' ids; if any specified Agent is in the chat, the webhook will be triggered.
`filters.chat_member_ids.agents_exclude`	No	`[]string`	Array of Agents' ids; If any specified Agent is in the chat, the webhook will not be triggered.

Triggering actions

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

Possible action	Informs about	Available filters
`incoming_chat_thread`	`incoming_chat_thread`	`chat_member_ids`, `only_my_chats`
`incoming_event`	`incoming_event`	`chat_member_ids`, `author_type`, `only_my_chats`
`event_updated`	`event_updated`	`chat_member_ids`, `author_type`, `only_my_chats`
`incoming_rich_message_postback`	`incoming_rich_message_postback`	`chat_member_ids`, `only_my_chats`
`last_seen_timestamp_updated`	`last_seen_timestamp_updated`	`chat_member_ids`, `only_my_chats`
`thread_closed`	`thread_closed`	`chat_member_ids`, `only_my_chats`
`chat_properties_updated`	`chat_properties_updated`	`chat_member_ids`, `only_my_chats`
`chat_properties_deleted`	`chat_properties_deleted`	`chat_member_ids`, `only_my_chats`
`chat_thread_properties_updated`	`chat_thread_properties_updated`	`chat_member_ids`, `only_my_chats`
`chat_thread_properties_deleted`	`chat_thread_properties_deleted`	`chat_member_ids`, `only_my_chats`
`chat_user_added`	`chat_user_added`	`chat_member_ids`, `only_my_chats`
`chat_user_removed`	`chat_user_removed`	`chat_member_ids`, `only_my_chats`
`chat_thread_tagged`	`chat_thread_tagged`	`chat_member_ids`, `only_my_chats`
`chat_thread_untagged`	`chat_thread_untagged`	`chat_member_ids`, `only_my_chats`
`agent_status_changed`	`agent_updated`	`chat_member_ids`
`agent_deleted`	An Agent's account being deleted from the license	`agent_ids`

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

Possible value	Available for actions
`access`	`incoming_event`, `chat_user_added`
`chat_properties`	All actions, except for `agent_status_changed` and `agent_deleted`
`thread_id`	`chat_user_added`

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/register_webhook \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "url": "http://myservice.com/webhooks",
        "description": "Test webhook",
        "action": "thread_closed",
        "secret_key": "laudla991lamda0pnoaa0"  
        }'

Response

Copied!

{
  "webhook_id": "pqi8oasdjahuakndw9nsad9na"
}

Get Webhooks Config

Specifics


Method URL	`https://api.livechatinc.com/v3.1/configuration/action/get_webhooks_config`
Required scopes	`webhooks--my:ro` `webhooks--all:ro`

REQUEST

Copied!

curl -X POST \
  https://api.livechatinc.com/v3.1/configuration/action/get_webhooks_config \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'

Response

Copied!

[
    {
      "webhook_id": "pqi8oasdjahuakndw9nsad9na",
      "url": "http://myservice.com/webhooks",
      "description": "Test webhook",
      "action": "thread_closed",
      "filters": {
        "chat_member_ids": {
          "agents_any": ["johndoe@mail.com"]
        }
      },
      "owner_client_id": "asXdesldiAJSq9padj"
    }
]

Unregister Webhook

Specifics


Method URL	`https://api.livechatinc.com/v3.1/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.1/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.1, visit the Webhooks document.

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@livechat.com. We'll be happy to hear from you!

Configuration API.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

.css-1plb8kr{color:inherit;-webkit-text-decoration:none;text-decoration:none;position:relative;}.css-1plb8kr:hover{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1plb8kr:hover:before{content:"#";position:absolute;font-weight:300;left:-1em;top:1px;opacity:0.3;}Introduction

Configuration API

Introduction