Platform
APIs & SDKs
Resources

...

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.5. 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 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.5 in Postman. In our collection, we use environment variables that store, for example, the access token. Importing the collection from the link below downloads the environment as well. Remember to replace sample tokens with your own.

Run in Postman

Methods

Available methods

Batch requests

Batch requests make it possible to execute one method multiple times with different payloads, all in a single request.

Each request in a batch is executed concurrently – there's no guarantee regarding the execution order. The response for each method is returned in an array in the same order as in the batch request. It's not possibile to mix different methods in a single batch request, for example Create Agent and Update Agent. Batch requests require the same scopes as their non-batch equivalents.

Request

ParameterRequiredData typeNotes
requestsyesarrayArray of request objects of the corresponding non-batch method
Format of request payload
Copied!
{
  "requests": [
    {<request object>},
    {<another request object>},
    ...
  ]
}

Response

FieldNotes
responsesArray of response objects or errors of the corresponding non-batch method. The order is the same as in the request.
Format of response payload
Copied!
{
  "responses": [
    {<response object or error>},
    {<another response object or error>},
    ...
  ]
}
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/batch_delete_agents \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "requests": [
          {
            "id": "smith@example.com"
          },
          {
            "id": "brown@example.com"
          },
          {}
        ]
      }'
Response
Copied!
{
  "responses": [
    {},
    {},
    {
      "error": {
        "type": "validation",
        "message": "`id` is required"
      }
    }
  ]
}

Methods with batch support

Batch support for Agents
MethodBatch method URL
Create Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_create_agents
Update Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_update_agents
Delete Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_delete_agents
Suspend Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_suspend_agents
Unsuspend Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_unsuspend_agents
Approve Agenthttps://api.livechatinc.com/v3.5/configuration/action/batch_approve_agents
Batch support for Bots
MethodBatch method URL
Create Bothttps://api.livechatinc.com/v3.5/configuration/action/batch_create_bots
Update Bothttps://api.livechatinc.com/v3.5/configuration/action/batch_update_bots
Delete Bothttps://api.livechatinc.com/v3.5/configuration/action/batch_delete_bots

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

Create Agent

Creates a new agent with specified parameters within a license.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/create_agent
Required scopesaccounts--all:rc accounts--all:rw1 subscription.lc:rw1 2 accounts.roles.lc--all:rw3
Batch supportYes

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
ParameterData typeRequiredNotes
idstringYesAgent ID
namestringYesAgent name
rolestringNoAgent role, should be one of the following: viceowner, administrator, normal (default).
avatarstringNoAvatar URL
login_statusstringNoAgent's default status right after the login, should be one of the following: accepting chats, not accepting chats (default).
job_titlestringNoAgent's job title
mobilestringNoAgent's mobile number
max_chats_countintNoAgent's maximum number of concurrent chats; default: 6. Limited to 100.
awaiting_approvalboolNoDetermines if the Agent will be awaiting approval after creation. Only a requester with the subscription.lc:rw scope can set this value to false.
groupsobject[]NoGroups an Agent belongs to.
groups[].iduintYesGroup ID; required only when group is included.
groups[].priority4stringYesAgent's priority in a group; required only when group is included.
notifications5string[]NoRepresents which Agent notifications are turned on.
email_subscriptions6string[]NoRepresents which subscriptions will be send to the Agent via email.
work_schedulerobjectNoWork scheduler options to set for the new Agent
work_scheduler.timezonestringYesTimezone for the work scheduler. Required only when schedule is not empty. Falls back to the agent's timezone if empty.
work_scheduler.scheduleobject[]YesList of agent's working hours.
work_scheduler.schedule[].daystringYesThe day for which the working hours are set. Possible values: sunday, monday, tuesday, wednesday, thursday, friday, and saturday.
work_scheduler.schedule[].enabledboolYesWhether the given set of working hours is enabled.
work_scheduler.schedule[].startstringYesWhen working hours start.
work_scheduler.schedule[].endstringYesWhen working hours end.

4) 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.
supervisorAgents with the supervisor priority will not get any chats assigned automatically.

5) Possible values for the notifications array:

  • new_visitor
  • incoming_chat
  • returning_visitor
  • queued_visitor
  • visitor_is_typing
  • new_goal
  • unassigned_chats
  • unassigned_chat_messages
  • ticket
  • inactive_notifications
  • mute_all_sounds
  • repeat_sound_notifications
  • ticket_notifications
  • incoming_message_for_focused_chat

6) Possible values for the email_subscriptions array:

  • daily_summary
  • weekly_summary
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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": {
        "schedule": [
            {
                "day": "monday",
                "start": "08:00",
                "end": "12:30",
                "enabled": true
            },
            {
                "day": "monday",
                "start": "13:30",
                "end": "16:00",
                "enabled": true
            },
            {
                "day": "friday",
                "start": "08:00",
                "end": "16:00",
                "enabled": true
            }
        ],
        "timezone": "Europe/Warsaw"
    },
        "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.5/configuration/action/get_agent
Required scopesagents--my:ro agents--all:ro
Batch supportNo
Request
ParameterTypeRequiredNotes
idstringYesAgent ID
fields1string[]NoAdditional fields to include.

1) Possible values for the fields[] parameter:

Possible valueNotes
work_schedulerWork scheduler object for an Agent. See Create Agent for details.
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
last_logoutRFC 3339 date-time of the last logout of an Agent (omitted when no logout occurred)
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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",
	"account_id": "d24fa41e-bc16-41b8-a15b-9ca45ff7e0cf",
	"name": "Agent Smith",
	"avatar": "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.5/configuration/action/list_agents
Required scopesagents--all:ro
Batch supportNo
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).
filters.suspendedNoboolIf provided, returns only those Agents who have the same suspended field value.
fields1Nostring[]Additional Agent fields to include.

1) Possible values for the fields[] parameter:

Possible valueNotes
groupsGroups an Agent belongs to
work_schedulerWork scheduler object for an Agent. See Create Agent for details.
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
last_logoutRFC 3339 date-time of the last logout of an Agent (omitted when no logout occurred)
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_agents \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
       "fields": [
          "email_subscriptions",
          "max_chats_count",
          "job_title",
          "last_logout"
        ],
        "filters": {
          "group_ids": [
            0,
            1
          ]
        }
    }'
Response
Copied!
[
	{
		"avatar_path": "cdn.livechatinc.com/avatars/1.png",
		"id": "smith@example.com",
		"account_id": "d24fa41e-bc16-41b8-a15b-9ca45ff7e0cf",
		"job_title": "Support Hero",
		"login_status": "not accepting chats",
		"name": "Smith",
		"role": "owner",
		"max_chats_count": 5,
		"summaries": [
			"daily_summary",
			"weekly_summary"
		]
	},
	{
		"avatar_path": "cdn.livechatinc.com/avatars/2.png",
		"id": "jones@example.com",
		"account_id": "2fca3315-f6b2-422f-8550-c84b649cef1a",
		"job_title": "Support Hero (Newbie)",
		"login_status": "accepting chats",
		"last_logout": "2022-08-23T14:31:21.000000Z",
		"name": "Jones",
		"role": "viceowner",
		"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.5/configuration/action/update_agent
Required scopesagents--my:rw agents--all:rw1 accounts.roles.lc--all:rw2
Batch supportYes

1) to update other agents within the same license
2) to update the agent role

Request
ParameterData typeRequiredNotes
idstringYesAgent ID
namestringNoAgent name
rolestringNoAgent role, should be one of the following: viceowner, administrator, normal
avatarstringNoAvatar URL
login_statusstringNoAgent's default status right after the login, should be one of the following: accepting chats, not accepting chats (default).
job_titlestringNoAgent's job title
mobilestringNoAgent's mobile number
max_chats_countintNoAgent's maximum number of concurrent. Limited to 20. chats
groupsobject[]NoGroups an Agent belongs to.
groups[].iduintYesGroup ID; required only when group's included.
groups[].priority 3stringYesAgent's priority in a group; required only when group's included.
notifications4string[]NoRepresents which Agent notifications are turned on.
email_subscriptions5string[]NoRepresents which subscriptions will be send to an Agent via email.
work_schedulerobjectNoWork scheduler options to set for an Agent. See Create Agent for details.

3) 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.
supervisorAgents with the supervisor priority will not get any chats assigned automatically.

4) Possible values for the notifications array:

  • new_visitor
  • incoming_chat
  • returning_visitor
  • queued_visitor
  • visitor_is_typing
  • new_goal
  • unassigned_chats
  • unassigned_chat_messages
  • ticket
  • inactive_notifications
  • mute_all_sounds
  • repeat_sound_notifications
  • ticket_notifications
  • incoming_message_for_focused_chat

5) Possible values for the email_subscriptions array:

  • daily_summary
  • weekly_summary
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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.5/configuration/action/delete_agent
Required scopesagents--my:rw accounts--my:rw agents--all:rw 1 accounts--all:rw 1
Batch supportYes

1) to delete other agents within the same license

Request
ParameterRequiredData typeNotes
idYesstringAgent ID
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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 URLhttps://api.livechatinc.com/v3.5/configuration/action/suspend_agent
Required scopesagents--all:rw sessions--all:rw1
Batch supportYes

1) sessions--all:rw 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.5/configuration/action/suspend_agent \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "id": "smith@example.com"
      }'

Unsuspend Agent

Unsuspends an Agent specified by id.

❗️ This method is not yet available for public use. For now, an agent can only be approved via the LiveChat Agent application UI. We would love to hear how you'd like to use this method -- please send us an email at developers@text.com describing your use case.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/unsuspend_agent
Required scopesagents--all:rw accounts--all:rw subscription.lc:rw1
Batch supportYes

1) subscription.lc:rw 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.5/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.5/configuration/action/request_agent_unsuspension
Required scopes-
Batch supportYes
Request

Empty request payload.

Response

No response payload (200 OK).

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

Approve Agent

Approves an Agent thus allowing the Agent to use the application.

❗️ This method is not yet available for public use. For now, an agent can only be approved via the LiveChat Agent application UI. We would love to hear how you'd like to use this method -- please send us an email at developers@text.com describing your use case.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/approve_agent
Required scopesagents--all:rw accounts--all:rw subscription.lc:rw 1
Batch supportYes

1) subscription.lc:rw 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.5/configuration/action/approve_agent \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "id": "smith@example.com"
      }'

Auto access

Auto access allows you to assign groups to a thread that will be created when a customer starts a chat. Those groups are assigned based on the conditions defined to match the customer's geolocation and the page URL the customer is currently visiting. Every time a customer calls Login or Update Customer Page, our backend checks if the page URL and geolocation match the pre-defined conditions. Given there's a match, the groups are assigned to a thread, but not until a chat starts and the thread is actually created.

If a customer starts a chat via Start Chat or Activate Chat with the chat.access parameter, chat.access overrides the auto access assigned to the thread.

Auto access rules are ordered using a linked list. Each of them points to the next element by keeping its id in the next_id field. For the last element of the list, the next_id is empty.

Methods

Add Auto Access

Creates an auto access data structure, which is a set of conditions for the tracking URL and geolocation of a customer.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/add_auto_access
Required scopesaccess_rules:rw
Batch supportNo
ParameterRequiredData typeNotes
accessYesobjectDestination access
access.groupsYes[]intDestination groups
conditions1YesobjectConditions to check
conditions.urlNoobjectThe condition that matches on customer_page.url from Login or url from Update Customer Page
conditions.domainNoobjectThe condition that matches on the domain of the customer_url
conditions.{url,domain}.valuesNo[]match_object2Positive match, may not be used together with exclude_values
conditions.{url,domain}.exclude_valuesNo[]match_objectNegative match
conditions.geolocationNoobjectThe condition that matches on the customer's geolocation
conditions.geolocation.valuesYes[]geolocation_object3An array of objects; matches when at least one subcondition matches.
descriptionNostringDescription of the auto access
next_idNostringID of an existing auto access. Leave empty if the new auto access should be the last one on the list.

1) conditions must have at least one of url, domain, geolocation set.

2) <match_object> structure:

ParameterRequiredData typeNotes
valueYesstringA value to match
exact_matchNoboolIf set to false, a match_object.value will be matched as a substring of the customer URL or domain.

3) the geolocation_object structure. The condition is fulfilled only when all of the specified fields match. At least one field must be specified.

ParameterRequiredData typeExample
countryNostring"United States"
country_codeNostring"US"
regionNostring"California"
cityNostring"Mountain View"
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/add_auto_access \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "description": "Chats on livechat.com from United States",
        "access": {
          "groups": [ 1 ]
        },
        "conditions": {
          "domain": {
            "values": [
              {
                "value": "livechat.com",
                "exact_match": true
              }
            ]
          },
          "geolocation": {
            "values": [
              {
                "country": "United States",
                "country_code": "US"
              }
            ]
          }
        },
        "next_id": "1faad6f5f1d6e8fdf27e8af9839783b7"
      }'
Response
Copied!
{
  "id": "pqi8oasdjahuakndw9nsad9na"
}

List Auto Accesses

Returns all existing auto access data structures.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_auto_accesses
Required scopesaccess_rules:ro
Batch supportNo
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_auto_accesses \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'
Response
Copied!
[
  {
    "id": "1faad6f5f1d6e8fdf27e8af9839783b7",
    "description": "Chats on livechat.com from United States",
    "access": {
      "groups": [
        0
      ]
    },
    "conditions": {
      "geolocation": {
        "values": [
          {
            "country": "United States",
            "country_code": "US"
          }
        ]
      },
      "domain": {
        "values": [
          {
            "value": "livechat.com",
            "exact_match": true
          }
        ]
      }
    },
    "next_id": "pqi8oasdjahuakndw9nsad9na"
  }
]

Delete Auto Access

Deletes an existing auto access data structure specified by its ID.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/delete_auto_access
Required scopesaccess_rules:rw
Batch supportNo
ParameterRequiredData typeNotes
idYesstringAuto access ID
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/delete_auto_access \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "id": "pqi8oasdjahuakndw9nsad9na"
  }'

Update Auto Access

Updates an existing auto access. Only specified fields are updated (overwritten), leaving unspecified fields unchanged.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/update_auto_access
Required scopesaccess_rules:rw
Batch supportNo
ParameterRequiredData typeNotes
idYesstringID of the auto access to modify
accessNoobjectDestination access
access.groupsYes[]intDestination groups
conditions1NoobjectConditions to check
conditions.urlNoobjectThe condition that matches on customer_page.url from Login or url from Update Customer Page
conditions.domainNoobjectThe condition that matches on the domain of the customer_url
conditions.{url,domain}.valuesNo[]match_object2Positive match, may not be used together with exclude_values
conditions.{url,domain}.exclude_valuesNo[]match_objectNegative match
conditions.geolocationNoobjectThe condition that matches on the customer's geolocation
conditions.geolocation.valuesYes[]geolocation_object3An array of objects; matches when at least one subcondition matches.
descriptionNostringDescription of the auto access
next_id4NostringID of an existing auto access. If next_id is an empty string, auto_access moves to the end of the list.

1) conditions must have at least one of url, domain, geolocation set.

2) <match_object> structure:

ParameterRequiredData typeNotes
valueYesstringA value to match
exact_matchNoboolIf set to false, a match_object.value will be matched as a substring of the customer URL or domain; default: false.

3) the geolocation_object structure. The condition is fulfilled only when all of the specified fields match. At least one field must be specified.

ParameterRequiredData typeExample
countryNostring"United States"
country_codeNostring"US"
regionNostring"California"
cityNostring"Mountain View"

4) Modifying next_id moves the auto access specified by id before the auto access that is specified by next_id. If next_id is an empty string, then auto access will be placed at the end of the list. If you don't intend to reorder the rule at all, don't include next_id in the request. To better understand it, analyze the example below.

💡 Example:

In the following list: A -> B -> C -> D -> null, letters represent the auto_access data structures while arrows indicate the next_id relation. Therefore, A has next_id set to B, B has next_id set to C, and so on.

An update_auto_access call with the {"id": "C", "next_id": "B"} payload would result in reordering the sequence, which after the successful request, would look like this: A -> C -> B -> D -> null. Consistency is maintained by keeping the next_id references properly assigned in each of the elements after a single request.

Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/update_auto_access \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "id": "pqi8oasdjahuakndw9nsad9na",
    "access": {
      "groups": [0, 42]
    },
    "next_id": "1faad6f5f1d6e8fdf27e8af9839783b7"
  }'

Bots

Bots enable writing integrations using the Agent Chat API to communicate in chats similarly to regular agents. Unlike agents, bots don't have passwords or emails - you cannot log in as a bot. Each bot is a resource owned by an application (client_id) in Developer Console.

There are two authorization mechanisms for bots:

  • old (v3.5 and lower): a bot shares the access token with the agent who created it. To make calls as a bot, you need to provide the agent token and the X-Author-Id header.
  • new (v3.5 and higher): bots use their own authorization tokens generated with the Issue Bot Token method.

Methods

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

Create Bot Template

Creates a new bot template for the Client ID (application) provided in the request. One Client ID can register up to five bot templates.

A bot based on a template will be automatically created on the license when the application is installed. Such a bot will have the same ID as the bot template. If the application is already installed on the license, the bot will be created only if affect_existing_installations is set to true.

Bots based on templates will work in the same way as those created by the Create Bot method.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/create_bot_template
Required scopesbots.templates:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameYesstringDisplay name
avatarNostringAvatar URL
max_chats_countNointMax. number of incoming chats that can be routed to the bot; default: 6. Limited to 500.
default_group_priority1NostringThe default routing priority for a group without defined priority.
job_titleNostringBot's job title
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
affect_existing_installationsNoboolIf set to true, a bot based on this template will be created on all licenses that have given application installed. Otherwise only new installations will trigger bot creation.

1) Possible priority values:

ValueNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBots with the supervisor priority will not get any chats assigned automatically.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/create_bot_template \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Bot Name"
      }'
Response
Copied!
{
	"id": "5c9871d5372c824cbf22d860a707a578",
	"secret": "641e2ae6d997d2009a3ac92a05f37fc3"
}

Create Bot

Creates a new bot. To make the bot available for receiving chats or webhooks, use the Set Routing Status method.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/create_bot
Required scopesagents-bot--my:rw
Batch supportYes
Request
ParameterRequiredData typeNotes
nameYesstringDisplay name
avatarNostringAvatar URL
max_chats_countNointMax. number of incoming chats that can be routed to the Bot; default: 6. Limited to 500.
default_group_priority1NostringThe default routing priority for a group without defined priority.
job_titleNostringBot's job title
groupsNoobject[]Groups the Bot belongs to.
groups[].idNointGroup ID; required only when group's included.
groups[].priority1YesstringBot's priority in a group; required only when group's included.
work_schedulerNoobjectWork scheduler options to set for the new Bot. See Create Agent for details.
work_scheduler.timezoneYesstringThe time zone in which the Bot's work scheduler should operate.
owner_client_id2YesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.

1) Possible priority values:

ValueNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBots with the supervisor priority will not get any chats assigned automatically.

2) The number of sent webhooks depends on the number of webhooks registered for an owner_client_id, not the number of bots belonging to that owner_client_id.

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/create_bot \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Bot Name"
      }'
Response
Copied!
{
	"id": "5c9871d5372c824cbf22d860a707a578",
	"secret": "641e2ae6d997d2009a3ac92a05f37fc3"
}

Delete Bot Template

Deletes a bot template specified by id. The bots associated with the template will be deleted only if affect_existing_installations is set to true.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/delete_bot_template
Required scopesbots.templates:rw
Batch supportNo
Request
ParameterRequiredTypeNotes
idYesstringBot Template ID
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
affect_existing_installationsNoboolIf set to true, a bot based on this template will be deleted from all licenses that have given application installed.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/delete_bot_template \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": "505591fc9fc2d6e92798bed7d9d8f079"
      }'

Delete Bot

Deletes a bot specified by id.

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

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/delete_bot \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": "505591fc9fc2d6e92798bed7d9d8f079"
      }'

Update Bot Template

Updates an existing bot template.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/update_bot_template
Required scopesbots.templates:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
idYesstringBot Template ID
nameNostringDisplay name
avatarNostringAvatar URL
max_chats_countNointMaximum incoming chats that can be routed to the Bot. Limited to 500.
default_group_priority1NostringThe default routing priority for a group without defined priority.
job_titleNostringBot's job title
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
affect_existing_installationsNoboolIf set to true, bots based on this template will be updated on all licenses that have given application installed.

1) Possible priority values:

ValueNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBots 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.5/configuration/action/update_bot_template \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": "ce54714e3d2b53adbfff09dbdbdd56e9",
      "name": "New Bot Name"
      }'

Update Bot

Updates an existing Bot.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/update_bot
Required scopesagents-bot--my:rw agents-bot--all:rw (to update other Bots within the same license)
Batch supportYes
Request
ParameterRequiredData typeNotes
idYesstringBot ID
nameNostringDisplay name
avatarNostringAvatar URL
max_chats_countNointMaximum incoming chats that can be routed to the Bot. Limited to 500.
groupsNoobject[]Groups the Bot belongs to
groups[].idYesuintGroup ID, required only when groups's present.
groups[].priority1YesstringBot's priority in the group; required only when groups is included.
default_group_priority1NostringThe default routing priority for a group without defined priority.
work_schedulerNoobjectWork scheduler options to set for the new Bot. See Create Agent for details.
work_scheduler.timezoneYesstringThe time zone in which the Bot's work scheduler should operate.

1) Possible priority values:

ValueNotes
firstThe 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.
normalThe 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.
lastThe 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.
supervisorBots 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.5/configuration/action/update_bot \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "id": "ce54714e3d2b53adbfff09dbdbdd56e9",
      "name": "New Bot Name"
      }'

List Bot Templates

Returns the list of bot templates created for a Client ID (application).

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_bot_templates
Required scopesbots.templates:rw
Batch supportNo
Request
ParameterRequiredTypeNotes
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_bot_templates \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'
Response
Copied!
[
	{
		"id": "2c1b8da190222160e8f9e077af4c625b",
		"name": "Bot Name",
		"avatar_path": "example.com/avatar.jpg"
	}
]

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.5/configuration/action/list_bots
Required scopesagents-bot--my:ro agents-bot--all:ro
Batch supportNo
Request
ParameterRequiredTypeNotes
allNobooltrue - gets all Bots within a license.  false (default)1 - returns only the requester's Bots.
fields2Nostring[]Additional Bot fields to include

1) Calling List Bots with all:false

  • If a Bot was created via an app, all Agents who make the request via this app will get the Bot in the response.
  • If a Bot was created directly by an Agent (PAT authorization), all Agents who authorize with PATs will get the Bot in the response.

2) Possible values for the fields[] parameter:

Possible valueNotes
groupsGroups a Bot belongs to
work_schedulerWork scheduler object for a Bot. See Create Agent for details.
job_titleBot's job title
max_chats_countBot's maximum number of concurrent chats
timezoneThe time zone in which the Bot's work scheduler operates
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_bots \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "all": false
      }'
Response
Copied!
[
	{
		"id": "2c1b8da190222160e8f9e077af4c625b",
		"name": "Bot Name",
		"avatar_path": "example.com/avatar.jpg"
	}
]

Get Bot

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

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/get_bot
Required scopesagents-bot--my:ro agents-bot--all:ro
Batch supportNo
Request
ParameterRequiredTypeNotes
idYesstringBot ID
fields1string[]NoAdditional fields to include.

1) Possible values for the fields[] parameter:

Possible valueNotes
work_schedulerWork scheduler object for a Bot. See Create Agent for details.
groupsGroups a Bot belongs to
job_titleBot's job title
max_chats_countBot's maximum number of concurrent chats
timezoneThe time zone in which the Bot's work scheduler operates
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/get_bot \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "id": "5c9871d5372c824cbf22d860a707a578"
      }'
Response
Copied!
{
	"id": "5c9871d5372c824cbf22d860a707a578",
	"name": "John Doe",
	"avatar_path": "https://example.com/avatar.jpg",
	"default_group_priority": "first",
	"owner_client_id": "asXdesldiAJSq9padj",
	"max_chats_count": 6,
	"groups": [
		{
			"id": 0,
			"priority": "normal"
		},
		{
			"id": 1,
			"priority": "normal"
		},
		{
			"id": 2,
			"priority": "first"
		}
	]
}

Issue Bot Token

Issues a new token for the bot. The token is valid for 24 hours. The token cannot be revoked.

The token has the following scopes that allow chatting: chats--access:rw, agents-bot--my:rw, customers:rw.

The required bot_secret is returned in Create Bot Template and Create Bot methods. If you lost the secret, you can reset it using Reset Bot Template Secret or Reset Bot Secret methods.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/issue_bot_token
Required scopes-
Batch supportNo
Request
ParameterRequiredTypeNotes
bot_idYesstringBot ID
client_idYesstringClient ID
bot_secretYesstringBot secret
organization_idYesstringOrganization ID
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/issue_bot_token \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "bot_id": "5c9871d5372c824cbf22d860a707a578",
        "client_id": "238ac5c3c3628210aca289c6d700d2c1",
        "bot_secret: "641e2ae6d997d2009a3ac92a05f37fc3",
        "organization_id": "1a8a9ec7-bd5d-4400-9204-3826740981e0"
      }'
Response
Copied!
{
	"token": "<JWT Bot token>"
}

Reset Bot Template Secret

Resets secret for given bot template.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/reset_bot_template_secret
Required scopesbots.templates:rw
Batch supportNo
Request
ParameterRequiredTypeNotes
idYesstringBot template ID
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
affect_existing_installationsNoboolIf set to true, the new secret is set to for all existing bots based on this template.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/reset_bot_template_secret \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "id": "5c9871d5372c824cbf22d860a707a578"
      }'
Response
Copied!
{
	"secret": "641e2ae6d997d2009a3ac92a05f37fc3"
}

Reset Bot Secret

Resets secret for a given bot.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/reset_bot_secret
Required scopesagents-bot--my:rw
Batch supportNo
Request
ParameterRequiredTypeNotes
idYesstringBot ID
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/reset_bot_secret \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "id": "5c9871d5372c824cbf22d860a707a578"
      }'
Response
Copied!
{
	"secret": "641e2ae6d997d2009a3ac92a05f37fc3"
}

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.5/configuration/action/<action>
Required headerValue
Content-Typeapplication/json

Create Group

Creates a new group.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/create_group
Required scopesgroups--all:rw
Batch supportNo
Request
ParameterData typeRequiredNotes
namestringYesGroup name (up to 180 chars)
language_codestringNoThe code of the group languange
agent_priorities1objectYesAgents' 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 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.
supervisorAgents with the supervisor priority will not get any chats assigned automatically.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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.5/configuration/action/update_group
Required scopesgroups--my:rw groups--all:rw (to update groups the requester is not a member of)
Batch supportNo
Request
ParameterData typeRequiredNotes
idintYesGroup ID
namestringNoGroup name (up to 180 chars)
language_codestringNoThe code of the group languange
agent_priorities1objectNoAgents' 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 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.
supervisorAgents 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.5/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.5/configuration/action/delete_group
Required scopesgroups--my:rw groups--all:rw (to delete groups the requester is not a member of)
Batch supportNo
Request
ParameterData typeRequiredNotes
idintYesGroup ID
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/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.5/configuration/action/list_groups
Required scopesgroups--all:ro
Batch supportNo
Request
ParameterData typeRequiredNotes
fields1string[]NoAdditional fields to include.

1) 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.5/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.5/configuration/action/get_group
Required scopesgroups--my:ro groups--all:ro (to get groups the requester is not a member of)
Batch supportNo
Request
ParameterData typeRequiredNotes
idintYesGroup ID
fields1string[]NoAdditional fields to include.

1) 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.5/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. Property configuration is owned by a Client Id (integration). In this document, we call a Client Id that owns a property the owner Client Id.

Properties can be private or public.

  • Private properties can be accessed only by their owner Client Id. Read more...
  • Public properties can be accessed by any Client Id. Read more...

Properties are grouped in namespaces, which helps to distinguish which property belongs to a given Client Id. The property namespace is named after the Client Id a property belongs to.

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

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

Property types

There are four property types:

  • int (int32)
  • bool
  • string
  • tokenized_string

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

Property locations

Properties can be set within the following locations:

  • event
  • thread
  • chat
  • group
  • license

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

Property domain

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

Property domain can be configured in two ways:

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

Property default value

If a property value hasn't been explicitly set, then the default value will be returned, if any. The default value of a property can be set during property registration as the default_value parameter.

Private properties

You can register, unregister, and configure a property for a Client Id owned by your organization. Unpublished (private) properties can be access only with a token belonging to the owner Client Id. If you want other integrations to be able to access your private property, you need to publish it.

Public properties

Once you publish a private property, it becomes accessible to other integrations. The public access to your property can be read and/or write. Consider an example:

You register a private chat property with the read and write access.

{
    "name": "string_property",
    "owner_client_id": "0805e283233042b37f460ed8fbf22160",
    "type": "string",
    "access": {
      "chat": {
        "agent": ["read"],
        "customer": ["read", "write"]
      }
    }
}

While publishing the property, you can narrow down its public access to read.

curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/publish_property \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "string_property",
    "owner_client_id": "0805e283233042b37f460ed8fbf22160",
    "access_type": ["read"]
}'

In this case, tokens belonging to the owner Client Id will be able to read and write to that property. Any other token will only be able to read it.

💡 Published properties cannot be unregistered.

Test properties

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

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.

Predefined properties

There are also predefined public properties used mainly by the LiveChat backend integration.

Methods

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

Register Property

Registers a new private property for a given Client Id.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/register_property
Required scopesproperties.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameYesstringProperty name
owner_client_idYesstringClient Id that will own the property; must be owned by your organization.
typeYesstringPossible values: int, string, bool, and tokenized_string
accessYesobject
access.<location>min. one locationobjectPossible values: chat, thread, event, license, group
access.<location>.<user>min. one user[string]Possible <user> values: agent, customer; possible values: read, write
descriptionNostringProperty description
domain 1No[<type>]Array of values that properties can be set to
range 1NoobjectRange of values that properties can be set to
range.fromNointOnly values equal or greater than this parameter can be set to this property
range.toNointOnly values equal or lower than this parameter can be set to this property
default_value 2NotypeDefault value of property; validated by domain or range, if one exists

1) Only one domain and one range can be set for a single property.
2) Registering a property with default_value is possible only if access.<location> is set to license or to group.

Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/register_property \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "string_property",
    "owner_client_id": "0805e283233042b37f460ed8fbf22160",
    "type": "string",
    "default_value": "string_default_value",
    "access": {
      "chat": {
        "agent": ["read"],
        "customer": ["read", "write"]
      }
      //  "thread": {},
      //  "event": {},
      //  "license": {},
      //  "group": {}
    }
}'

Unregister Property

Unregisters a private property.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/unregister_property
Required scopesproperties.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameYesstringProperty name
owner_client_idYesstringClient Id that owns the property; must be owned by your organization
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/unregister_property \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "string_property",
    "owner_client_id": "0805e283233042b37f460ed8fbf22160"
}'

Publish Property

Publishes a private property. A published property cannot be unpublished or unregistered. Published properties can be accessed by tokens belonging to any Client Id.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/publish_property
Required scopesproperties.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameYesstringProperty name
owner_client_idYesstringClient Id that owns the property; must be owned by your organization.
access_typeYes[string]Possible values: read, write. It determines the access level for the Client Ids different than owner_client_id.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/publish_property \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "string_property",
    "owner_client_id": "0805e283233042b37f460ed8fbf22160",
    "access_type": ["read"]
}'

List Properties

Lists private and public properties owned by a given Client Id.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_properties
Required scopesproperties.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
owner_client_idYesstringClient Id that owns the properties; must be owned by your organization.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_properties \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "owner_client_id": "0805e283233042b37f460ed8fbf22160"
  }'
Response
Copied!
{
	"string_property": {
		"type": "string",
		"description": "",
		"access": {
			"thread": {
				"agent": [
					"read",
					"write"
				],
				"customer": [
					"read"
				]
			},
			"chat": {
				"agent": [
					"write"
				],
				"customer": [
					"read",
					"write"
				]
			}
		},
		"public_access": [
			"read"
		]
	}
}

Update License Properties

Updates a property value within a license. This operation doesn't overwrite the existing values.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/update_license_properties
Required scopesproperties.license.value--my:rw1, properties.license.value--all:rw2
Batch supportNo

1) If the requester's Client ID matches the namespace, setting license properties requires properties.license.value--my:rw.

2) If the requester's Client ID doesn't match the namespace, setting license properties requires properties.license.value--all:rw. The scope allows to set all properties from your namespace and public properties from core and other namespaces.

Request
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.5/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. For properties without an explicit value assignment, the method will return the default values (if they exist).

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_license_properties
Required scopesproperties.license.value--my:ro1, properties.license.value--all:ro2
Batch supportNo

1) The properties.license.value--my:ro scope allows you to access all properties from your namespace only.

2) The properties.license.value--all:ro scope allows you to access all properties from your namespace and public properties from core and other namespaces.

Request
ParameterRequiredData typeNotes
namespaceNostringProperties namespace
name_prefixNostringProperties name prefix
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_license_properties \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
      "namespace": "0805e283233042b37f460ed8fbf22160",
      "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.5/configuration/action/delete_license_properties
Required scopesproperties.license.value--my:rw1, properties.license.value--all:rw2
Batch supportNo

1) If the requester's Client ID matches the namespace, deleting license properties requires properties.license.value--my:rw.

2) If the requester's Client ID doesn't match the namespace, deleting license properties requires properties.license.value--all:rw. The scope allows to delete all properties from your namespace and public properties from core and other namespaces.

Request
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.5/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.5/configuration/action/update_group_properties
Required scopesproperties.group.value--my:rw1, properties.group.value--all:rw2
Batch supportNo

1) If the requester's Client ID matches the namespace, setting group properties requires properties.group.value--my:rw.

2) If the requester's Client ID doesn't match the namespace, setting group properties requires properties.group.value--all:rw. The scope allows to set all properties from your namespace and public properties from other namespaces.

Request
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.5/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 Groups Properties

Returns the properties set within specified groups.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_groups_properties
Required scopesproperties.group.value--all:ro
Batch supportNo
Request
ParameterRequiredData typeNotes
group_idsYes[]intIDs of the groups you retrieve properties from. Properties from all groups will be returned if an empty array is provided.
namespaceNostringProperties namespace
name_prefixNostringProperties name prefix
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_groups_properties \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
     "group_ids": [0, 1],
     "namespace": "a",
     "name_prefix": "b"
     }'
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.5/configuration/action/delete_group_properties
Required scopesproperties.group.value--my:rw1, properties.group.value--all:rw2
Batch supportNo

1) If the requester's Client ID matches the namespace, deleting group properties requires properties.group.value--my:rw.

2) If the requester's Client ID doesn't match the namespace, deleting group properties requires properties.group.value--all:rw. The scope allows to delete all properties from your namespace and public properties from other namespaces.

Request
ParameterRequiredData typeNotes
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.5/configuration/action/delete_group_properties \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
      "id": 1,
      "properties": {
        "0805e283233042b37f460ed8fbf22160": ["string_property"]
          }
      }'

Tags

Tags are simple text labels that can be used by agents to assign chats to pre-defined, custom categories. Tags are useful for filtering out chats in archives and reports.

To create a new tag, call the Create Tag method with a name. Letter case is ignored when checking if a tag already exists. When creating a tag, you can also provide group_ids to assign the tag to some groups right away. It's also possible to create a tag with empty group_ids and update the group assignment later with Update Tag.

To remove a tag, call Delete Tag. Both Update Tag and Delete Tag methods respect the letter case when matching the tag. You can list all tags existing on your account with the List Tags method.

Users with the tags--all:rw scope can create/delete/update tags in all license's groups. Users with the tags--groups:rw scope are restricted to groups they are assigned to. Similarly tags--all:ro and tags--groups:ro scopes affect listing tags.

Tag can be used to mark a chat's thread only if the thread and the tag are assigned to at least one common group.

Methods

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

Create Tag

Creates a new tag.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/create_tag
Required scopestags--all:rw tags--groups:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameyesstringMatching the name of an existing tag is case insensitive.
group_idsno[]intCan be empty.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/create_tag \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "docs_feedback",
    "group_ids": [
      0,
      42
    ]
  }'

Delete Tag

Deletes an existing tag.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/delete_tag
Required scopestags--all:rw tags--groups:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameyesstringMatching the name of an existing tag is case sensitive.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/delete_tag \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "docs_feedback"
  }'

List Tags

Lists the exisiting tags.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_tags
Required scopestags--all:ro tags--groups:ro
Batch supportNo
Request
ParameterRequiredData typeNotes
filtersNoobjectPossible request filters.
filters.group_idsYesint[]IDs of the groups from which you want to list tags.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_tags \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "group_ids": [
        0,
        42
      ]
    }
  }'
Response
Copied!
[
	{
		"name": "docs_feedback",
		"group_ids": [
			0,
			42
		],
		"author_id": "smith@example.com",
		"created_at": "2019-12-09T12:01:18.909000Z"
	},
	{
		"name": "positive feedback",
		"group_ids": [
			0
		],
		"author_id": "",
		"created_at": "2017-11-13T15:37:36.000000+01:00"
	},
	{
		"name": "support",
		"group_ids": [
			0
		],
		"author_id": "",
		"created_at": "2017-11-13T15:37:36.000000+01:00"
	},
	{
		"name": "complaint",
		"group_ids": [
			0
		],
		"author_id": "",
		"created_at": "2017-11-13T15:37:36.000000+01:00"
	},
	{
		"name": "sales",
		"group_ids": [
			0
		],
		"author_id": "",
		"created_at": "2017-11-13T15:37:36.000000+01:00"
	},
	{
		"name": "spam",
		"group_ids": [
			0
		],
		"author_id": "",
		"created_at": "2017-11-13T15:37:36.000000+01:00"
	}
]

Update Tag

Updates an existing tag.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/update_tag
Required scopestags--all:rw tags--groups:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
nameyesstringMatching the name of an existing tag is case sensitive.
group_idsno[]intCan be empty.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/update_tag \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "name": "docs_feedback",
    "group_ids": [
      0,
      42
    ]
  }'

Sample app

Tag Master allows you to create, view, and delete tags and canned responses in an easy and predictable way. It uses Accounts SDK and its Redirect method for authorization and Configuration API v3.5 endpoints:

To read more and experiment with the Tag Master app, go on our GitHub. You can also check out our different sample apps here.

Webhooks

Here's what you need to know about webhooks:

  • Webhooks notify you when specific events are triggered.
  • They can be generated by both Web and RTM API actions.
  • Webhooks and pushes have similar payloads.
  • You register webhook definitions per Client ID (application).
  • Webhooks are always automatically enabled for the licences that install your application.
  • There's a limit of three weebhoks for every action a Client ID can register.

💡 Tutorial: How to set up LiveChat webhooks.

general webhook format
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "<action>",
  "organization_id": "<organization_id>",
  "payload": {
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Methods

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

Register Webhook

Registers a webhook for the Client ID (application) provided in the request. One Client ID can register up to three webhooks for every action. The license webhooks'll be enabled automatically when the application is installed on the license.

As an alternative to calling Register Webhook, you can register webhooks via Developer Console by configuring the Chat Webhooks building block. Learn more...

For bot webhooks, you need to create a bot, register webhooks, and then, call Set Routing Status.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/register_webhook
Required token scopes 1webhooks.configuration:rw
Batch supportNo

1) Token scopes are assigned to an access token, not to an application (Client ID). For this method, we recommend authorizing with a Personal Access Token (PAT). Make sure your PAT has the webhooks.configuration:rw scope.

ParameterRequiredData typeNotes
action2yesstringThe 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, chat_presence_user_ids (all actions except for agent_status_changed, agent_deleted, incoming_customer)
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_presencenoobjectFilters to check if a webhook should be triggered based on user's presence in the chat.
filters.chat_presence.user_idsnoobjectOnly one filter (values or exclude_values) is allowed. Supports every user type (Agent, Customer, Bot).
filters.chat_presence.user_ids.valuesno[]stringArray of Users' ids; if any specified User is in the chat, the webhook will be triggered.
filters.chat_presence.user_ids.exclude_valuesno[]stringArray of Users' ids; if any specified Users is in the chat, the webhook will not be triggered.
filters.chat_presence.my_botsnoboolIf any bot owned by owner_client_id is in the chat, the webhook will be triggered.
filters.source_typeno[]stringArray of source types. Possible values: my_client (client ID of your app), other_clients (client IDs other than your app's), system (no client ID); if the source which triggered the webhook matches the filter, the webhook will be sent.
owner_client_idyesstringThe Client ID for which the webhook will be registered. What is Client ID and where to find it?. Required only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
typeyesstringbot or license
Triggering actions

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

Possible actionAvailable filters
incoming_chatchat_presence, only_my_chats, source_type
chat_deactivatedchat_presence, only_my_chats, source_type
chat_access_updatedchat_presence, only_my_chats, source_type
chat_transferredchat_presence, only_my_chats, source_type
user_added_to_chatchat_presence, only_my_chats, source_type
user_removed_from_chatchat_presence, only_my_chats, source_type
incoming_eventchat_presence, author_type, only_my_chats, source_type
event_updatedchat_presence, author_type, only_my_chats, source_type
incoming_rich_message_postbackchat_presence, only_my_chats, source_type
chat_properties_updatedchat_presence, only_my_chats, source_type
chat_properties_deletedchat_presence, only_my_chats, source_type
thread_properties_updatedchat_presence, only_my_chats, source_type
thread_properties_deletedchat_presence, only_my_chats, source_type
event_properties_updatedchat_presence, only_my_chats, source_type
event_properties_deletedchat_presence, only_my_chats, source_type
thread_taggedchat_presence, only_my_chats, source_type
thread_untaggedchat_presence, only_my_chats, source_type
routing_status_setagent_ids, source_type
incoming_customersource_type
customer_session_fields_updatedchat_presence, source_type
events_marked_as_seenchat_presence, only_my_chats, source_type
group_createdsource_type
group_updatedsource_type
group_deletedsource_type
agent_createdsource_type
agent_updatedsource_type
agent_deletedsource_type
agent_suspendedsource_type
agent_unsuspendedsource_type
agent_approvedsource_type
bot_createdsource_type
bot_updatedsource_type
bot_deletedsource_type
auto_accesses_updatedsource_type
tag_createdsource_type
tag_deletedsource_type
tag_updatedsource_type
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/register_webhook \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic <your_username>:<your_PAT>' \
  -d '{
        "url": "http://myservice.com/webhooks",
        "description": "Test webhook",
        "action": "chat_deactivated",
        "secret_key": "laudla991lamda0pnoaa0",
        "owner_client_id": "asXdesldiAJSq9padj",
        "type": "license"
      }'
Response
Copied!
{
	"id": "pqi8oasdjahuakndw9nsad9na"
}

List Webhooks

Lists all webhooks registered for the given Client ID.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_webhooks
Required scopeswebhooks.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
owner_client_idyesstringThe webhook owner (the Client ID for which the webhook is registered). Required only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_webhooks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "owner_client_id": "0805e283233042b37f460ed8fbf22160"
  }'
Response
Copied!
[
	{
		"id": "pqi8oasdjahuakndw9nsad9na",
		"url": "http://myservice.com/webhooks",
		"description": "Test webhook",
		"action": "chat_deactivated",
		"filters": {
			"chat_presence": {
				"user_ids": {
					"values": [
						"johndoe@mail.com"
					]
				},
				"my_bots": true
			}
		},
		"owner_client_id": "asXdesldiAJSq9padj",
		"type": "license"
	}
]

Unregister Webhook

Unregisters a webhook previously registered for a Client ID (application).

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/unregister_webhook
Required scopeswebhooks.configuration:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
idYesstringWebhook ID
owner_client_idYesstringThe webhook owner (the Client ID for which the webhook is registered). Required only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/unregister_webhook \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        "id": "pqi8oasdjahuakndw9nsad9na",
        "owner_client_id": "0805e283233042b37f460ed8fbf22160"
      }'

List Webhook Names

Lists all webhooks that are supported in a given API version. This method requires no authorization.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_webhook_names
Required scopes-
Batch supportNo
Request
ParameterRequiredData typeNotes
versionNostringDefaults to the current stable API version
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_webhook_names \
  -H 'Content-Type: application/json' \
  -d '{
        "version": "3.5"
      }'
Response
Copied!
[
	{
		"action": "agent_deleted",
		"filters": [
			"agent_ids"
		]
	},
	{
		"action": "chat_access_updated",
		"filters": [
			"chat_presence",
			"only_my_chats"
		],
		"additional_data": [
			"chat_properties",
			"chat_presence_user_ids"
		]
	},
	{
		"action": "incoming_customer"
	}
]

Enable License Webhooks

Enables the disabled webhooks on the license.

Use this method only if you disabled the webhooks on the license via Disable License Webhooks. Otherwise, the webhooks will be automatically enabled when the associated application is installed on the license.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/enable_license_webhooks
Required scopeswebhooks.state:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
Response

No response payload (200 OK).

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

Disable License Webhooks

Disables the webhooks on the license. The webhooks will stay disabled even after the associated application is reinstalled. To enable the webhooks again (and to rely on automatic webhooks enablement), use Enable License Webhooks.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/disable_license_webhooks
Required scopeswebhooks.state:rw
Batch supportNo
Request
ParameterRequiredData typeNotes
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
Response

No response payload (200 OK).

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

Get License Webhooks State

Gets the state of the webhooks registered for a given Client Id (application) on the license associated with the access token used in the request.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/get_license_webhooks_state
Required scopeswebhooks.state:ro
Batch supportNo
Request
ParameterRequiredData typeNotes
owner_client_idYesstringRequired only when authorizing via PATs. When you provide this param while authorizing with a Bearer Token, the client_id associated with the Bearer Token will be ignored, and provided owner_client_id will be used instead.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/get_license_webhooks_state \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
Copied!
{
	"license_webhooks_enabled": true
}

Available webhooks

To see the list of available webhooks v3.5, visit the Webhooks document.

Other

Methods

List Channels

Returns the summary of communication channels for your LiveChat product.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/list_channels
Required scopes-
Batch supportNo
Request

Empty request payload.

Response

The response is an array of the channel objects:

FieldData typeNotes
channel_typestringPossible values: code, direct_link or integration
channel_subtypestringPossible values: An empty string for code and direct_link; Client ID for integration
first_activity_timestampstringRFC 3339 date-time format
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/list_channels \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
Copied!
[
	{
		"channel_type": "code",
		"channel_subtype": "",
		"first_activity_timestamp": "2017-10-12T13:56:16Z"
	},
	{
		"channel_type": "direct_link",
		"channel_subtype": "",
		"first_activity_timestamp": "2017-10-12T15:20:00Z"
	},
	{
		"channel_type": "integration",
		"channel_subtype": "c6e4f62e2a2dab12531235b12c5a2a6b",
		"first_activity_timestamp": "2019-08-16T16:55:51Z"
	}
]

Check Product Limits for Plan

Resource limits in the LiveChat product are different for each plan. This method compares your organization's current resources with a given plan and returns those which exceeded the called plan's limits. Useful when considering downgrading the plan.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/check_product_limits_for_plan
Required scopessubscription.lc:rw1
Batch supportNo

1) subscription.lc:rw is a private scope; it's not possible to configure it in Developer Console.

Request
ParameterRequiredData typeNotes
planyesstringPossible values: starter, team, enterprise, enterpriseplus
Response
Resource NameNotes
agentsThe number of active agents, including bots, that exceeded the limit.
groupsThe number of groups that exceeded the limit.
bannedThe number of banned visitors that exceeded the limit.
queueThe number of chats waiting in the queue (with Messaging Mode disabled) that exceeded the limit.
queue_continuousThe number of chats waiting in the queue (with Messaging Mode enabled) that exceeded the limit.
groups_per_agentThe number of groups an agent can be assigned to that exceeded the limit.
access_rulesThe number of Access Rules that exceeded the limit.
group_chooser_groupsThe number of groups available in the pre-chat survey that exceeded the limit.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/check_product_limits_for_plan \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "plan": "starter"
      }'
Response
Copied!
[
	{
		"resource": "groups",
		"limit_balance": 1
	},
	{
		"resource": "groups_per_agent",
		"limit_balance": 2,
		"id": "user@example.com"
	},
	{
		"resource": "group_chooser_groups",
		"limit_balance": 3,
		"id": "0"
	},
	{
		"resource": "queue",
		"limit_balance": 4
	},
	{
		"resource": "queue",
		"limit_balance": 4,
		"id": "0"
	},
	{
		"resource": "queue_continuous",
		"limit_balance": 1
	},
	{
		"resource": "queue_continuous",
		"limit_balance": 1,
		"id": "0"
	},
	{
		"resource": "access_rules",
		"limit_balance": 1
	}
]

Get Product Source

This method retrieves the source parameters that were passed when activating the LiveChat product.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/configuration/action/get_product_source
Required scopes-
Request

Empty request payload.

Response
FieldData typeNotes
source_idstringThe source ID parameter passed when activating the LiveChat product.
source_typestringThe source type parameter passed when activating the LiveChat product.
source_urlstringThe source URL parameter passed when activating the LiveChat product.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.5/configuration/action/get_product_source \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
Copied!
{
	"source_id": "create_account_link",
	"source_type": "accounts",
	"source_url": "https://accounts.livechat.com"
}

Errors

Format of error payload
Copied!
{
  "error": {
    "type": "misdirected_request",
    "message": "Wrong region",
    "data": {
      // optional
      "region": "dal"
    }
  }
}

Possible errors

Error typeDefault messageDescription
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorUser is not allowed to perform the action.
already_existAlready existIt's impossible to create the resource as it already exists.
group_not_foundGroup not found
internalInternal server error
license_expiredLicense expiredThe end of license trial or subcription.
limit_reachedResource limit reachedResource cannot be created/modified because the change would exceed the limit
misdirected_requestWrong regionClient'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_foundNot foundThe requested resource wasn't found.
too_many_requestsToo many requestsThe request's rate limit was exceeded. It'll be unblocked automatically after some time.
transfer_ownershipTransfer ownershipOwnership cannot be transfered to this account (bot, suspended agent).
unsupported_versionUnsupported versionUnsupported protocol version.
validationWrong 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!

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@text.com