Platform
APIs & SDKs
Resources

...

Web API Reference

Introduction

Versioning

This document describes the Agent Chat Web API v3.3, which is a legacy version. For production-ready applications, it's best to use to the current stable version. Read more about versioning...

Lifecycle headers

API responses will contain one of two headers related to the API lifecycle: Legacy or Deprecation. These headers specify when the associated stage ends (in the YYYY-MM-DD format).

What is Web API

Web API is similar to REST API. Client can send a request message that results in getting a response message. It's also possible to get webhooks.

When to use Web API

If you're wondering which API to use - Agent Chat RTM API or Web API, keep on reading.

Web API allows for building stateless integrations. The communication is done via XHR requests. The implementation is easier than with RTM API, but you need to take possible time delays into consideration.

Not what you're looking for? Perhaps, you need to use Agent Chat RTM API instead.

Access

The basics on authorization, access tokens, and scopes in the Agent Chat Web API.

Authorization

Agent authorization is handled with access tokens. Find out how to get an access token from Agent authorization flows. Take note you won't be able to use this token for the Customer Chat API.

Scopes

All authorization scopes are listed in the Scopes document. If a method requires certain scopes, you'll find them included in the method description. Keep in mind that Web API requires authorization every time you make a request.

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.

Rate limits

To prevent sending a massive number of requests, there are rate limits for method calls. After exceeding those limits, the requester will get a Too many requests error in the response of a specific request. After some time, the request will be unblocked so it can be sent again.

Pagination

Pagination is a mechanism that allows splitting the database output into more manageable chunks of data. Based on the limit and sort order parameters, pagination is able to decide how many records will be returned at once and whether it should fetch the oldest or the latest data first.

Any filters that could be applied should be provided in first pagination request. In the response, you'll get the next_page_id and previous_page_id parameters. You should make the subsequent request using one of these parameters as page_id, depending on the direction of iteration: forward or backward.

The filters, limit, and sort_order parameters can't be provided along with page_id.

đź’ˇ The maximum duration of the page_id parameter before it expires is one month.

Postman collection

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

Run in Postman

Data structures

To find sample payloads of events, users, and other common structures such as chats or threads visit the Data structures document.

Methods

HTTP methodThe API endpoint
POSThttps://api.livechatinc.com/v3.3/agent/action/<action>

If you specify the API version in the URL, you don't have to include the optional "X-API-Version: 3.3" header.

Required HeaderValueNotes
Content-Typemultipart/form-data; boundary=<boundary>Valid for the upload_file method
Content-Typeapplication/jsonValid for all methods except for upload_file
AuthorizationBearer <token>Access token
X-Author-Id<bot_agent_id>Valid only for Bot Agents
GENERAL WEB API REQUEST FORMAT
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/<action> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    // payload
    }'

Available methods

Chats

List Chats

It returns summaries of the chats an Agent has access to.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_chats
Required scopeschats--all:ro chats--access:ro chats--my:ro
RTM API equivalentlist_chats
Webhook-
ParameterRequiredTypeNotes
filtersNoobjectWhen paginating, filters provided in the first request are remembered and automatically used for the subsequent requests. Providing a new filters object will result in a validation error. To reset the filters, start paginating with a new set of filters.
filters.include_activeNoboolDefines if the returned chat summary includes active chats; default: true.
filters.include_chats_without_threadsNoboolDefines if the returned chat summary includes chats without any threads; default: true.
filters.group_idsNoarrayArray of group IDs. Max array size: 200
filters.properties.<namespace>.<name>.<filter_type>Noany
sort_orderNostringPossible values: asc - oldest chats firstm desc - newest chats first (default)
limitNonumberDefault: 10, maximum: 100
page_idNostring

filter_type can take the following values:

  • exists (bool)
  • values (type[] - array with specific type for property: string, int, or bool)
  • exclude_values (type[] - array with specific type for property: string, int, or bool)

There's only one value allowed for a single property.

Response
FieldData typeNotes
chats_summaryarrayAn array of Chat summary data structures
next_page_idstringIn relation to page_id specified in the request. Appears in the response only when there's a next page.
previous_page_idstringIn relation to page_id specified in the request Appears in the response only when there's a previous page.
found_chatsnumberAn estimated number. The real number of found chats can slightly differ.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/list_chats \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{}'
Response
Copied!
{
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "chats_summary": [{
    "id": "PJ0MRSHTDG",
    "last_event_per_type": {
      "message": {
        "thread_id": "K600PKZON8",
        "thread_created_at": "2020-05-07T07:11:28.288340Z",
        "event": {
          "id": "Q298LUVPRH_1",
          "created_at": "2019-12-09T12:01:18.909000Z",
          "recipients": "all",
          "type": "message",
          "text": "hello world",
          "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
        }
      },
      "system_message": {
        "thread_id": "K600PKZON8",
        "thread_created_at": "2020-05-07T07:11:28.288340Z",
        "event": {
          // "System message" event
        }
      }
    },
    "users": [{
      // "Customer" user object
    }, {
      // "Agent" user object
    }],
    "last_thread_summary": {
      "id": "K600PKZON8",
      "created_at": "2020-05-07T07:11:28.288340Z",
      "user_ids": [
        "b7eff798-f8df-4364-8059-649c35c9ed0c",
        "smith@example.com"
      ],
      "properties": {
        // "Properties" object
      },
      "active": true,
      "access": {
        "group_ids": [0]
      }
    },
    "properties": {
      // "Properties" object
    },
    "access": {
      "group_ids": [0]
    },
    "is_followed": true
  }],
  "found_chats": 4
}

List Threads

It returns threads that the current Agent has access to in a given chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_threads
Required scopeschats--all:ro chats--access:ro chats--my:ro
RTM API equivalentlist_threads
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
sort_orderNostringPossible values: asc - oldest threads first and desc - newest threads first (default).
limitNonumberDefault: 3, maximum: 100
page_idNostring
min_events_countNonumberRange: 1-100; Specifies the minimum number of events to be returned in the response. It's the total number of events, so they can come from more than one thread. You'll get as many latest threads as needed to meet the min_events_count condition.
filtersNoobject
filters.fromNostringDate & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
filters.toNostringDate & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM

You cannot use either limit and min_events_count or filters and min_events_count at the same time.

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/list_threads \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PWJ8Y4THAV",
    }'
Response
Copied!
{
  "threads": [{
    "id": "K600PKZON8",
    "created_at": "2019-12-17T07:57:41.512000Z",
    "active": true,
    "user_ids": [
      "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "smith@example.com"
    ],
    "events": [{
      "id": "Q20N9CKRX2_1",
      "created_at": "2019-12-17T07:57:41.512000Z",
      "recipients": "all",
      "type": "message",
      "text": "Hello",
      "author_id": "smith@example.com"
    }],
    "properties": {
      // "Property" object
    },
    "access": {
      "group_ids": [0]
    },
    "previous_thread_id": "K600PKZOM8", // optional
    "next_thread_id": "K600PKZOO8" // optional
  }],
  "found_threads": 42,
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
}

Get Chat

It returns a thread that the current Agent has access to in a given chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/get_chat
Required scopeschats--all:ro chats--access:ro chats--my:ro
RTM API equivalentget_chat
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
thread_idNostringDefault: the latest thread (if exists)
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/get_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PWJ8Y4THAV",
      "thread_id": "K600PKZON8"
    }'
Response
Copied!
{
  "id": "PJ0MRSHTDG",
  "thread": {
    "id": "K600PKZON8",
    "created_at": "2020-05-07T07:11:28.288340Z",
    "active": true,
    "user_ids": [
      "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "smith@example.com"
    ],
    "events": [{
      "id": "Q20N9CKRX2_1",
      "created_at": "2019-12-17T07:57:41.512000Z",
      "recipients": "all",
      "type": "message",
      "text": "Hello",
      "author_id": "smith@example.com"
    }],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string_value"
      }
    },
    "access": {
      "group_ids": [0]
    },
    "previous_thread_id": "K600PKZOM8",
    "next_thread_id": "K600PKZOO8"
  },
  "users": [{
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "type": "customer",
    "present": true,
    "created_at": "2019-12-17T08:53:20.693553+01:00",
    "statistics": {
      "chats_count": 1
    },
    "agent_last_event_created_at": "2019-12-17T09:04:05.239000+01:00"
  }, {
    "id": "smith@example.com",
    "name": "Agent Smith",
    "email": "smith@example.com",
    "type": "agent",
    "present": true,
    "avatar": "https://example.com/avatar.jpg"
  }],
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "string_value"
    }
  },
  "access": {
    "group_ids": [0]
  },
  "is_followed": true
}

List Archives

It returns a list of the chats an Agent has access to. Together with a chat, the events of one thread from this chat are returned.

The list classification is based on threads; 1 chat per 1 thread. Thus, the same chat object may appear on the list several times, but each time with a different thread. The returned chat is a complete object, not only a chat summary.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_archives
Required scopeschats--all:ro chats--access:ro
RTM API equivalentlist_archives
Webhook-
Request
ParameterRequiredData typeNotes
filtersNoobject
filters.queryNostring
filters.fromNostringDate & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
filters.toNostringDate & time format compatible with RFC3339 with a resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
filters.thread_idsNoarrayArray of thread IDs. Cannot be used with other filters or pagination; max array size: 20.
filters.group_idsNoarrayArray of group IDs. Max array size: 200
filters.properties.<namespace>.<name>.<filter_type>Noany* described below
filters.agents.<filter_type>Noanyexists set to false will return unassigned chats; true will return the assigned ones.
filters.tags.<filter_type>Noany
filters.sales.<filter_type>Noany
filters.goals.<filter_type>Noany
filters.surveys.<survey>Noarray** described below
filters.events.typesNoarrayArray of Event types. Duplicates are ignored.
page_idNostring
sort_order ***NostringDefault: desc
limitNonumberDefault: 10, min: 1, max: 100
highlightsNoobjectUse it to highlight the match of filters.query. To enable highlights with default parameters, pass an empty object.
highlights.pre_tagNostringAn HTML tag to use for highlighting the matched text; default: <em>. Use it together with highlights.post_tag.
highlights.post_tagNostringAn HTML tag to use for highlighting the matched text; default: </em>. Use it together with highlights.pre_tag.

*) <filter_type> can take the following values:

  • exists (bool)
  • values (type[] - an array with a specific type for property: string, int or bool)
  • exclude_values (type[] - an array with a specific type for property: string, int or bool)

There's only one value allowed for a single property.

**) <survey> contains the following fields:

  • type (string) - allowed values: pre_chat, post_chat
  • answer_id (string)

***) sort_order can take the following values:

  • asc - the oldest chats first
  • desc - the newest chats first
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/list_archives \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "events": {
        "types": ["message", "filled_form"]
    }
  }
}'
Response
Copied!
{
  "chats": [
    {
      "id": "PJ0MRSHTDG",
      "users": [
        {
          "id": "smith@example.com",
          "name": "Agent Smith",
          "email": "smith@example.com",
          "type": "agent",
          "present": true,
          "avatar": "https://cdn.livechat-files.com/api/file/avatar.png"
        }
      ],
      "thread": {
        "id": "K600PKZON8",
        "active": false,
        "user_ids": [
          "smith@example.com"
        ],
        "events": [
          {
            "id": "QBT14H0Y3Y_1",
            "created_at": "2020-05-28T11:45:32.269000Z",
            "recipients": "all",
            "type": "message",
            "properties": {
              "0805e283233042b37f460ed8fbf22160": {
                "event_property": "property_value"
              }
            },
            "text": "Hello there",
            "author_id": "smith@example.com"
          }
        ],
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "thread_property": "property_value"
          }
        },
        "access": {
          "group_ids": [
            0
          ]
        },
        "created_at": "2020-05-28T11:44:58.829000Z"
      },
      "properties": {
        "0805e283233042b37f460ed8fbf22160": {
          "chat_property": "property_value"
        }
      },
      "access": {
        "group_ids": [
          0
        ]
      },
      "is_followed": false
    }
  ],
  "found_chats": 42,
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==",
  "previous_page_id": "MTUxNzM5ODEzMTQ5Ng=="
}

Start Chat

Starts a chat.

The method updates the requester's events_seen_up_to as if they've seen all chat events.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/start_chat
Required scopes *chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentstart_chat
Webhookincoming_chat

*) When chat.users is defined, one of following scopes is required:

  • chats--all:rw
  • chats--access:rw
  • chats--my:rw
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobject
chat.accessNoobject
chat.usersNo[]objectThe list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
chat.users.idYesstringUser ID
chat.users.typeYesstringagent or customer
chat.threadNoobject
chat.thread.eventsNoarrayThe list of initial chat events object. Does not support the form type event in the LiveChat app.
chat.thread.propertiesNoobject
activeNoboolWhen set to false, creates an inactive thread; default: true.
continuousNoboolStarts chat as continuous (online group is not required); default: false.
Response
FieldData typeNotes
chat_idstring
thread_idstring
event_ids[]stringReturned only when the chat was started with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/start_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "PGDGHT5G"
}

Resume Chat

Restarts an archived chat.

The method updates the requester's events_seen_up_to as if they've seen all chat events.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/resume_chat
Required scopes *chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentresume_chat
Webhookincoming_chat

*) When chat.users is defined, one of following scopes is required:

  • chats--all:rw
  • chats--access:rw
  • chats--my:rw
Request
ParameterRequiredData typeNotes
chatYesobject
chat.idYesstringID of the chat that will be resumed.
chat.accessNoobjectChat access to set, default: all agents.
chat.propertiesNoobjectInitial chat properties
chat.usersNo[]objectThe list of existing users. Up to 4 additional (other than the requester) agents and 1 customer allowed.
chat.users.idYesstringUser ID
chat.users.typeYesstringagent or customer
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial thread properties
activeNoboolWhen set to false, creates an inactive thread; default: true.
continuousNoboolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Response
FieldData typeNotes
thread_idstring
event_ids[]stringReturned only when the chat was resumed with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/resume_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat": {
      "id": "PWJ8Y4THAV"
      }
    }'
Response
Copied!
{
  "thread_id": "Z8AGR5OUW"
}

Deactivate Chat

Deactivates a chat by closing the currently open thread. Sending messages to this thread will no longer be possible.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/deactivate_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentdeactivate_chat
Webhookchat_deactivated
Request
ParameterRequiredData type
idYesstring
Response

No response payload (200 OK).

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

Follow Chat

Marks a chat as followed. All changes to the chat will be sent to the requester until the chat is reactivated or unfollowed. Chat members don't need to follow their chats. They receive all chat pushes regardless of their follower status.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/follow_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentfollow_chat
Webhook-
Request
ParameterRequiredData type
idYesstring
Response

No response payload (200 OK).

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

Unfollow Chat

Removes the requester from the chat followers. After that, only key changes to the chat (like transfer_chat or close_active_thread) will be sent to the requester. Chat members cannot unfollow the chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/unfollow_chat
Required scopes-
RTM API equivalentunfollow_chat
Webhook-
Request
ParameterRequiredData type
idYesstring
Response

No response payload (200 OK).

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

Chat access

Grant Chat Access

Grants access to a new chat without overwriting the existing ones.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/grant_chat_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentgrant_chat_access
Webhookchat_access_granted
Request
ParameterRequiredData typeNotes
idYesstringChat Id
accessYesobject
access.typeYesstringgroup
access.idYesany
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/grant_chat_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "id": "PW94SJTGW6",
  "access": {
    "type": "group",
    "id": 19
    }
  }'

Revoke Chat Access

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/revoke_chat_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentrevoke_chat_access
Webhookchat_access_revoked
Request
ParameterRequiredData typeNotes
idYesstringChat Id
accessYesobject
access.typeYesstringgroup or agent
access.idYesnumber
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/revoke_chat_access \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "id": "PW94SJTGW6",
   "access": {
     "type": "group",
     "id": 19
     }
   }'

Transfer Chat

Transfers a chat to an agent or a group. When transferring directly to an agent, the agent must have access to the transferred chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/transfer_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalenttransfer_chat
Webhookchat_transferred
Request
ParameterRequiredData typeNotes
idYesstringChat Id
targetNoobjectIf missing, the chat will be transferred within the current group.
target.typeYesstringgroup or agent
target.idsYesarraygroup or agent IDs array
forceNoboolIf true, always transfers chats. Otherwise, fails when unable to assign any agent from the requested groups; default false.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/transfer_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "PJ0MRSHTDG",
    "target": {
      "type": "group",
      "ids": [
        19
      ]
    }
  }'

Chat users

Add User to Chat

Adds a user to the chat. You can't add more than one customer user type to the chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/add_user_to_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentadd_user_to_chat
Webhookuser_added_to_chat
Request
ParameterRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible values: agent or customer
require_active_threadNoboolIf true, it adds a user to a chat only if that chat has an active thread; default false.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/add_user_to_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PW94SJTGW6",
    "user_id": "smith@example.com",
    "user_type": "agent",
    "require_active_thread": "true"
  }'

Remove User from Chat

Removes a user from chat. Removing customer user type is not allowed. It's always possible to remove the requester from the chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/remove_user_from_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentremove_user_from_chat
Webhookuser_removed_from_chat
Request
ParameterRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible value: agent
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/remove_user_from_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PW94SJTGW6",
    "user_id": "smith@example.com",
    "user_type": "agent"
  }'

Events

Send Event

Sends an Event object. Use this method to send a message by specifying the Message event type in the request.

It's possible to write to a chat without joining it. The user sending an event will be automatically added to the chat with the present parameter set to false (see user_added_to_chat). Sample use case: a Bot Agent that sends messages visible to all chat participants without actually joining the chat.

The method updates the requester's events_seen_up_to as if they've seen all chat events.

To call the API as a bot, use the X-Author-Id header set to the bot's id.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/send_event
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentsend_event
Webhookincoming_event
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to send a message to.
eventYesobjectEvent object. Does not support the form type event in the LiveChat app.
attach_to_last_threadNoboolThe flag is ignored for active chats. For inactive chats: true – the event will be added to the last thread; false – the request will fail. Default: false.
Response
FieldData type
event_idstring
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/send_event \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PW94SJTGW6",
   "event": {
     "type": "message",
     "text": "hello world",
     "recipients": "all"
     }
   }'
Response
Copied!
{
  "event_id": "K600PKZON8"
}

Upload File

Uploads a file to the server as a temporary file. It returns a URL that expires after 24 hours unless the URL is used in send_event.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/upload_file
RTM API equivalent-
Webhookincoming_event *

*) incoming_event returns a URL that never expires.

Request
ParameterRequiredData typeNotes
fileYesbinarymaximum size: 10MB
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/upload_file \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: multipart/form-data; boundary=--------------------------210197025774705439685896' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F file=@/Users/MyAccount/Desktop/image.png
Response
Copied!
{
  "url": "https://cdn.livechat-files.com/api/file/lc/att/8948324/45a3581b59a7295145c3825c86ec7ab3/image.png"
}

Send Rich Message Postback

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/send_rich_message_postback
Required scopeschats.conversation--my:rw chats.conversation--all:rw
RTM API equivalentsend_rich_message_postback
Webhookincoming_rich_message_postback*

*) incoming_rich_message_postback will be sent only for active threads.

Request
ParameterRequiredData typeNotes
chat_idYesstring
event_idYesstring
postbackYesobject
postback.idYesstringPostback name of the button
postback.toggledYesboolPostback toggled true/false
thread_idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/send_rich_message_postback \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "thread_id": "K600PKZON8",
   "event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
   "postback": {
     "id": "Method URL_yes",
     "toggled": true
     }
   }'

Properties

Update Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/update_chat_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentupdate_chat_properties
Webhookchat_properties_updated
Request
ParameterRequiredData typeNotes
idYesstringId of the chat you to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "id": "Q1VZR7AJCE",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat property value updated by Agent"
        }
     }
  }'

Delete Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/delete_chat_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentdelete_chat_properties
Webhookchat_properties_deleted
Request
ParameterRequiredData typeNotes
idYesstringId of the chat you want to delete property of.
propertiesYesobjectChat properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
  curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/delete_chat_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "Q1VZR7AJCE",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": [
        "string_property"
        ]
      }
    }'

Update Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/update_thread_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentupdate_thread_properties
Webhookthread_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.3/agent/action/update_thread_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": "Q1WZ073OA7",
    "thread_id": "Q1WZ073OB7",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "Chat thread property value updated by Agent"
        }
      }
    }'

Delete Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/delete_thread_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentdelete_thread_properties
Webhookthread_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
thread_idYesstringId of the thread you want to delete properties of.
propertiesYesobjectThread properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/delete_thread_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q1WZ073OA7",
  "thread_id": "Q1WZ073OB7",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }'

Update Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/update_event_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentupdate_event_properties
Webhookevent_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
event_idYesstringId of the event you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/update_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Event property value updated by Agent"
      }
    }
  }'

Delete Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/delete_event_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentdelete_event_properties
Webhookevent_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
event_idYesstringId of the event you want to delete the properties of.
propertiesYesobjectEvent properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/delete_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "Q16ZSBGX3J",
  "thread_id": "Q16ZSBGX4J",
  "event_id": "Q16ZSBGX4J_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": [
      "string_property"
      ]
    }
  }'

Thread tags

Tag Thread

Tags a given thread.

Read how to list all available tags and create a new tag.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/tag_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalenttag_thread
Webhookthread_tagged
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to add a tag to.
thread_idYesstringId of the thread you want to add a tag to.
tagYesstringTag name. It's case sensitive.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/tag_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
   }'

Untag Thread

Untags a given thread.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/untag_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentuntag_thread
Webhookthread_untagged
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to remove a tag from.
thread_idYesstringId of the thread you want to remove a tag from.
tagYesstringTag name. It's case sensitive.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/untag_thread \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PW94SJTGW6",
  "thread_id": "PWS6GIKAKH",
  "tag": "support"
   }'

Customers

Get Customer

Returns the info about the Customer with a given id.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/get_customer
Required scopescustomers:ro
RTM API equivalentget_customer
Push message-
Request
ParameterRequiredData typeNotes
idYesstring
Response
FieldData typeNotes
idstringCustomer's ID.
typestringcustomer
namestringCustomer's name. Returned only if set.
emailstringCustomer's email. Returned only if set.
avatarstringCustomer's avatar. Returned only if set.
created_atstringSpecifies when the customer's identity was created.
session_fields[]objectAn array of custom object-enclosed key:value pairs. Returned only if set. Available for the session duration.
statisticsobjectCounters for started threads, opened pages, etc.
last_visitobjectGeolocation and opened pages from the customer's most recent online visit. Returned only if the customer logged in at least once.
chat_ids[]stringIDs of a customer's chats. Returned only if the customer had at least one chat.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/get_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }'
Response
Copied!
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "created_at": "2017-10-11T15:19:21.010200Z",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "example.com/avatars/1.jpg",
  "session_fields": [{
    "custom_key": "custom_value"
  }, {
    "another_custom_key": "another_custom_value"
  }],
  "last_visit": {
    "started_at": "2017-10-12T15:19:21.010200Z",
    "ended_at": "2017-10-12T15:20:22.010200Z",
    "referrer": "http://www.google.com/",
    "ip": "<customer_ip>",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
    "geolocation": {
      "latitude": "-14.6973803",
      "longitude": "-75.1266898",
      "country": "Poland",
      "country_code": "PL",
      "region": "Dolnoslaskie",
      "city": "Wroclaw",
      "timezone": "Europe/Warsaw"
    },
    "last_pages": [{
      "opened_at": "2017-10-12T15:19:21.010200Z",
      "url": "https://www.livechat.com/",
      "title": "LiveChat - Homepage"
    }, {
      "opened_at": "2017-10-12T15:19:21.010200Z",
      "url": "https://www.livechat.com/tour",
      "title": "LiveChat - Tour"
    }]
  },
  "statistics": {
  "chats_count": 3,
  "threads_count": 9,
  "visits_count": 5,
  "page_views_count": 1337,
  "greetings_shown_count": 69,
  "greetings_accepted_count": 42
  },
  "__priv_lc2_customer_id": "test_771305.dafea66e5c", // old customer_id
  "agent_last_event_created_at": "2017-10-12T15:19:21.010200Z",
  "customer_last_event_created_at": "2017-10-12T15:19:21.010200Z",
  "chat_ids": [
  "PWJ8Y4THAV"
  ]
}

List Customers

It returns the list of Customers.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_customers
Required scopescustomers:ro
RTM API equivalentlist_customers
Webhook-
Request

All parameters are optional.

ParameterData typeNotes
page_idstring
limitnumberDefault: 10, maximum: 100
sort_order *stringDefault: desc
sort_by **stringDefault: created_at
filtersobject
filters.country.<string_filter_type> ***object
filters.email.<string_filter_type> ***object
filters.name.<string_filter_type> ***object
filters.customer_id.<string_filter_type> ***object
filters.chats_count.<range_filter_type> ****object
filters.threads_count.<range_filter_type> ****object
filters.visits_count.<range_filter_type> ****object
filters.created_at.<date_range_filter_type>*****object
filters.agent_last_event_created_at.<date_range_filter_type> *****object
filters.customer_last_event_created_at.<date_range_filter_type> *****object
filters.chat_group_ids.<integer_filter_type> ***objectMaximum 40 group ids at once
filters.include_customers_without_chatsbool

*)

sort_order can take the following values:

  • asc
  • desc

**)

sort_by can take the following values:

  • created_at
  • threads_count
  • visits_count
  • agent_last_event
  • customer_last_event

When sorting by fields other than created_at, the entries with identical values will be additionally sorted by their creation time.

***)

<string_filter_type> can take the following values :

  • values (string[] - an array of strings)
  • exclude_values (string[] - an array of strings)

<integer_filter_type> can take the following values:

  • values (int[] - an array of integers)
  • exclude_values (int[] - an array of integers)

There's only one value allowed for a single filter.

****)

<range_filter_type> can take the following values:

  • lte (int - less than or equal to given value)
  • lt (int - less than given value)
  • gte (int - greater than or equal to given value)
  • gt (int - greater than given value)
  • eq (int - equal to given value)

*****)

<date_range_filter_type> can take the following values:

  • lte ( string - less than or equal to given value)
  • lt (string - less than given value)
  • gte (string - greater than or equal to given value)
  • gt (string - greater than given value)
  • eq (string - equal to given value)

Dates are represented in ISO 8601 format with microseconds resolution, e.g. 2017-10-12T15:19:21.010200+01:00 in specific timezone or 2017-10-12T14:19:21.010200Z in UTC.

Response
FieldData typeNotes
next_page_idstringIn relation to page_id specified in the request.
previous_page_idstringIn relation to page_id specified in the request.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/list_customers \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
  "customers": [
  // array of "User > Customer" objects
  ],
  "total_customers": 2340,
  "limited_customers": 120, // optional
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Ng==" // optional
}

Create Customer

Creates a new Customer user type.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/create_customer
Required scopescustomers:rw
RTM API equivalentcreate_customer
Webhookincoming_customer
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar
session_fieldsNo[]objectAn array of custom object-enclosed key:value pairs. Respects the order of items.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/create_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Thomas Anderson",
    "email": "t.anderson@example.com",
    "avatar": "https://example.com/avatars/1.png",
    "session_fields": [{
    "custom_key": "custom_value"
    }, {
    "another_custom_key": "another_custom_value"
    }]
  }'
Response
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}

Update Customer

Updates Customer's properties.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/update_customer
Required scopescustomers:rw
RTM API equivalentupdate_customer
Webhookcustomer_session_fields_updated *

* The webhook will be sent only if the customer has active chats.

Request
ParameterRequiredData typeNotes
idYesstringUUID v4 format is required
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar
session_fieldsNo[]objectAn array of custom object-enclosed key:value pairs. Respects the order of items.

Apart from id, which is a required parameter, you also need to include one of the optional parameters.

When updating customer data while the customer has an active chat, the update will take effect after the chat has ended.

Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/update_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "name": "Thomas Anderson"
    "email": "t.anderson@example.com",
    "avatar": "https://example.com/avatars/1.png",
    "session_fields": [{
    "custom_key": "custom_value"
    }, {
    "another_custom_key": "another_custom_value"
    }]
  }'
Response
Copied!
{}

Ban Customer

Bans the customer for a specific period of time. It immediately disconnects all active sessions of this customer and does not accept new ones during the ban lifespan.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/ban_customer
Required scopescustomers.ban:rw
RTM API equivalentban_customer
Webhook-
Request
ParameterRequiredData type
idYesstring
banYesobject
ban.daysYesnumber
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/ban_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
   "ban": {
     "days": 3
     }
   }'

Follow Customer

Marks a customer as followed. As a result, the requester (an agent) will receive the info about all the changes related to that customer via pushes. Once the customer leaves the website or is unfollowed, the agent will no longer receive that information.

Following a customer causes the agent to receive customer-related pushes as long as the followed customer is available. The followed customer may be transferred to a group the agent doesn't have access to, which makes the customer unavailable to the agent. At that moment, the agent stops receiving pushes related to that customer. When the customer is transferred back and becomes available again, the pushes resume.

Agents don't need to follow the customers they're chatting with in order to receive related pushes. Agents will be receiving pushes related to those customers as long as the chats last.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/follow_customer
Required scopescustomers:ro
RTM API equivalentfollow_customer
Webhook-
Request
ParameterRequiredData type
idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/follow_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
   }'

Unfollow Customer

Removes the agent from the list of customer's followers. Calling this method on a customer the agent's chatting with will result in success, however, the agent will still receive pushes about the customer's data updates. The unfollowing will take effect once the chat ends.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/unfollow_customer
Required scopes-
RTM API equivalentunfollow_customer
Webhook-
Request
ParameterRequiredData type
idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/unfollow_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
   }'

Status

Set Routing Status

Changes the status of an Agent or a Bot Agent.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/set_routing_status
Required scopesfor Agents: agents--my:rw agents--all:rw; for Bot Agents: agents-bot--my:rw agents-bot--all:rw
RTM API equivalentset_routing_status
Webhookrouting_status_set
Request
ParameterRequiredData typeNotes
statusYesstringFor Agents: accepting_chats or not_accepting_chats; for Bot Agents: accepting_chats, not_accepting_chats, or offline
agent_idNostringIf not specified, the requester's status will be updated.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/set_routing_status \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "status": "accepting_chats",
    "agent_id": "smith@example.com"
  }'

List Routing Statuses

Returns the current routing status of each agent selected by the provided filters.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_routing_statuses
Required scopesagents--all:ro, agents-bot--all:ro
RTM API equivalentlist_routing_statuses
Webhook-
Request
ParameterRequiredTypeNotes
filtersNoobject
filters.group_idsNoarray
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/list_routing_statuses \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "filters": {
      "group_ids": [
        0
      ]
    }
  }'
Response
Copied!
[{
  "agent_id": "smith@example.com",
  "status": "accepting_chats"
}, {
  "agent_id": "agent@example.com",
  "status": "not_accepting_chats"
}]

Other

Mark Events as Seen

It marks an agent’s events up to a specific time as read in a customer’s chat window.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/mark_events_as_seen
Required scopeschats--access:ro chats--all:ro
RTM API equivalentmark_events_as_seen
Webhookevents_marked_as_seen
Request
ParameterRequiredData typeNotes
chat_idYesstring
seen_up_toYesstringRFC 3339 date-time format
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/mark_events_as_seen \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "seen_up_to": "2017-10-12T15:19:21.010200Z"
   }'

Send Typing Indicator

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/send_typing_indicator
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentsend_typing_indicator
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat that to send the typing indicator to.
recipientsNostringDefault: all; agents
is_typingYesbool
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/send_typing_indicator \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PJ0MRSHTDG",
   "is_typing": true
   }'

Multicast

This method serves for the chat-unrelated communication. Messages sent using multicast are not being saved.

For example, it could be used in an app that sends notifications to Agents or Customers, when a certain condition is met (e.g. an important Customer started the chat).

Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/multicast
Required scopesmulticast:rw
RTM API equivalentmulticast
Webhook-
Request
ParameterRequiredData typeNotes
recipientsYesobject*
contentYesanyA JSON message to be sent
typeNostringMulticast message type

*) recipients can take the following values:

  • agents:

    • all (bool - includes all agents)
    • ids ([]string - an array of agents' IDs)
    • groups ([]string - an array of groups' IDs)
  • customers:

    • ids ([]string - an array of customer's IDs)

At least one recipients type (agents.all, agents.ids, agents.groups, customers.ids) is required.

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/multicast \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "recipients": {
    "agents": {
      "all": true,
      "ids": [
      "smith@example.com",
      "agent@example.com"
      ],
      "groups": [
      1,
      2
      ]
    },
    "customers": {
      "ids": [
      "b7eff798-f8df-4364-8059-649c35c9ed0c"
      ]
    }
    },
    "content": {
    "example": {
      "nested": "json"
    }
    }
  }'

List Agents For Transfer

It returns the Agents you can transfer a chat to. Agents are sorted ascendingly by the total number of active chats they have. Note that:

  • The method only returns Agents with statuses online and not accepting chats. Offline Agents aren't returned.
  • Only chats with Customers are taken into account in total_active_chats.
Specifics
Method URLhttps://api.livechatinc.com/v3.3/agent/action/list_agents_for_transfer
Required scopes-
RTM API equivalentlist_agents_for_transfer
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstringThe ID of the chat you want to transfer
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/list_agents_for_transfer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "chat_id": "PJ0MRSHTDG"
  }'
Response
Copied!
[{
  "agent_id": "smith@example.com",
  "total_active_chats": 2
}, {
  "agent_id": "agent@example.com",
  "total_active_chats": 5
}]

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.
  • When using RTM API, you can be also notified about events with pushes.
  • Webhooks and pushes have similar payloads.
  • There's a limit of three weebhoks for every action a Client ID can register.

You can create and manage webhooks via the Configuration API.

See webhook methodsSee webhook payloads

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.
chat_inactiveNo active chat threadAn action that requires an active thread performed on a chat with no active threads.
entity_too_largeUpload limit exceeded (10MB).Client's request is too large.
internalInternal server error
license_expiredLicense expiredThe end of license trial or subcription.
license_not_foundLicense not foundLicense with the specified ID doesn't exist.
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.
request_timeoutRequest timed outTimeout threshold is 15 seconds.
service_unavailableNot accepting new requestsNew requests are temporarily not being accepted.
too_many_requestsToo many requestsThe request's rate limit was exceeded. It'll be unblocked automatically after some time.
unsupported_versionUnsupported versionUnsupported protocol version.
validationWrong format of request
wrong_product_versionWrong product versionLicense is not LiveChat 3 (probably still LiveChat 2).

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