API version

Web API Reference

7 minutes reading time

Introduction

Versioning

This document describes the Agent Chat Web API v3.1. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...

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

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

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.

Postman collection

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

Run in Postman

Events

One of the data structures are events. They are sent to a chat via the send_event method. Apart from events, there are also Properties, Users, and Other common data structures.

These are the available event types:

File

The File event informs about an uploaded file.

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfile
recipientsyesstringPossible values: all (default), agents
propertiesnoobjectProperties
urlyesstringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
recipientsalways
propertiesoptionally
namealways
urlalways
thumbnail_url, thumbnail2x_urlonly for images
content_typealways
size, width, heightonly for images
Sample File in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "file",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"properties": {},
	"name": "image25.png",
	"url": "https://example.com/image25.png",
	"thumbnail_url": "https://example.com/thumbnail.png",
	"thumbnail2x_url": "https://example.com/thumbnail2x.png",
	"content_type": "image/png",
	"size": 123444,
	"width": 640,
	"height": 480
}

Filled form

The Filled form event contains data from a form (prechat or postchat survey).

Request

FieldRequiredData typeNotes
custom_idnostring
typeyesstringfilled_form
recipientsyesstringPossible values: all (default), agents
propertiesnoobjectProperties
form_idyesstring
fieldsyesarrayThe fields a form contains. See form fields for details.

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealways
author_idalways
recipientsalways
propertiesoptionally
form_idalways
fieldsalwaysAn array of form fields
Sample Filled form in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"properties": {},
	"form_id": "1473433500211",
	"fields": [
		{
			"type": "name",
			"id": "154417206262603539",
			"label": "Your name",
			"answer": "John Doe"
		},
		{
			"type": "email",
			"id": "154417206262601584",
			"label": "Your email",
			"answer": "customer1@example.com"
		},
		{
			"type": "radio",
			"id": "154417206262602571",
			"label": "Chat purpose",
			"answer": {
				"id": "0",
				"label": "Support"
			}
		},
		{
			"type": "checkbox",
			"id": "154417206262604640",
			"label": "Company industry",
			"answers": [
				{
					"id": "0",
					"label": "automotive"
				},
				{
					"id": "1",
					"label": "it"
				}
			]
		},
		{
			"type": "group_chooser",
			"id": "154417206262605324",
			"label": "Choose department",
			"answer": {
				"group_id": 1,
				"label": "Marketing"
			}
		}
	]
}

Message

The Message event contains text message to other chat users.

Request

FieldRequiredData typeNotes
custom_idnostring
textyesstringMax. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
typeyesstringmessage
recipientsyesstringPossible values: all (default), agents
propertiesnoobjectProperties
postbacknoobjectIndicates that the message event was generated in response to a rich message event.
postback.idyesstringID of the postback from the rich message event.
postback.thread_idyesstringID of the thread with the rich message event.
postback.event_idyesstringID of the rich message event.
postback.typenostringShould be used together with postback.value (when one of them is present, the other is required).
postback.valuenostringShould be used together with postback.type (when one of them is present, the other is required).

Response

FieldReturnedNotes
idalways
custom_idoptionally
created_atalwaysDate & time format with a resolution of microseconds, UTC string.
typealwaysmessage
author_idalways
recipientsalways
textalways
postbackoptionallyAppears in a message only when triggered by a rich message.
postback.idalways
postback.thread_idalways
postback.event_idalways
postback.typeoptionallyAppears only if postback.value is present.
postback.valueoptionallyAppears only if postback.type is present.
propertiesoptionallyProperties
Sample Message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"text": "hello there",
	"postback": {
		"id": "action_call",
		"thread_id": "K600PKZON8",
		"event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
		"type": "phone",
		"value": "790034890"
	},
	"recipients": "all",
	"properties": {}
}

Rich message

Rich message (RM) event contains a rich message data structure. Read more about rich messages.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give your RM a custom ID.
typeyesstringEvent type: rich_message
recipientsyesstringThose who can display the rich message: all (default) or agents
propertiesnoobjectThe properties data structure
template_idyesstringDefines how every Rich Message will be presented. Values: cards, sticker, or quick_replies.
elementsnoarrayCan contain up to 10 element objects.
elements.titleyesstringDisplays formatted text on RMs.
elements.subtitleyesstringDisplays formatted text on RMs.
elements.imageyesimageDisplays images on RMs. Required param: url; Optional params: name, content_type, size, width, height.
elements.buttonsnoarrayDisplays buttons. Can contain up to 11 button objects.
elements.buttons.textyesstringText displayed on a button.
elements.buttons.typeyesarrayDefines the behavior after a user clicks the button. Should be used together with elements.buttons.value. Possible values: webview, message, url, phone. More...
elements.buttons.valueyesstringShould be used together with elements.buttons.type.
elements.buttons.webview_heightyesstringRequired only for the webview buttontype. Possible values: compact, full, tall.
elements.buttons.postback_idyesstringA description of the sent action. Describes the action sent via send_rich_message_postback. More...
elements.buttons.user_idsyesarrayDescribes users that sent the postback with "toggled": true.

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string. Generated server-side.
recipientsalways
propertiesoptionally
template_idalways
elementsoptionally
elements.titlealways
elements.subtitlealways
elements.imagealways
elements.buttonsoptionally
elements.buttons.textalways
elements.buttons.typealways
elements.buttons.valuealways
elements.buttons.webview_heightalwaysUnless button type is different than webview.
elements.buttons.postback_idalways
elements.buttons.user_idsalways
Sample Rich message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "rich_message",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"recipients": "all",
	"properties": {},
	"template_id": "cards",
	"elements": [
		{
			"title": "Lorem ipsum dolor.",
			"subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"image": {
				"name": "image25.png",
				"url": "https://example.com/image25.png",
				"content_type": "image/png",
				"size": 123444,
				"width": 640,
				"height": 480
			},
			"buttons": [
				{
					"text": "yes",
					"postback_id": "action_yes",
					"user_ids": [
						"b7eff798-f8df-4364-8059-649c35c9ed0c"
					]
				},
				{
					"text": "no",
					"postback_id": "action_no",
					"user_ids": []
				},
				{
					"type": "phone",
					"text": "value",
					"value": "790034890",
					"webview_height": "tall",
					"postback_id": "action_call",
					"user_ids": []
				}
			]
		}
	]
}

Custom

Custom event is an event with customizable payload.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give the event a custom ID.
typeyesstringEvent type: custom
contentnoobjectThe content you define
recipientsyesstringThose who can receive the custom event: all (default) or agents
propertiesnoobjectThe properties data structure

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
author_idalwaysGenerated server-side
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
contentoptionally
recipientsalways
propertiesoptionally
Sample Custom in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "custom",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"content": {
		"custom": {
			"nested": "json"
		}
	},
	"recipients": "all",
	"properties": {}
}

System message

System message event is native system event sent in specific situations.

Request

FieldRequiredData typeNotes
custom_idnostringYou can give the system message a custom ID.
typeyesstringsystem_message
textnostringText displayed to recipients
system_message_typeyesstringSystem message type
recipientsnostringIt can be specified when sending system messages via the Send Event method. Possible values: all, agents.
text_varsnoobjectVariables used in the text

Response

FieldReturnedNotes
idalwaysGenerated server-side
custom_idoptionally
typealways
created_atalwaysDate & time format with a resolution of microseconds, UTC string; generated server-side
textoptionally
system_message_typealways
recipientsoptionally
Sample System message in response
Copied!
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
	"custom_id": "31-0C-1C-07-DB-16",
	"type": "system_message",
	"created_at": "2017-10-12T15:19:21.010200Z",
	"text": "Hello there!",
	"system_message_type": "routing.assigned",
	"text_vars": {
		"agent": "John Doe"
	}
}

Users

Users are another important data structure. Within this data structure type, we can distinguish:

Agent

Sample Agent data structure
Copied!
{
  "id": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@example.com",
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "routing_status": "accepting_chats"
}
FieldReq./Opt.Note
routing_statusoptionalReturned only if the Agent is currently logged in.

My profile

Sample My profile data structure
Copied!
{
  "id": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "email": "agent1@example.com",
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "routing_status": "accepting_chats",
  "permission": "administrator"
}

Customer

Sample Customer data structure
Copied!
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "example.com/avatars/1.png",
  "last_visit": {
    "started_at": "2017-10-12T15:19:21.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": {
      "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.livechatinc.com/",
        "title": "LiveChat - Homepage"
      },
      {
        "opened_at": "2017-10-12T15:19:21.010200Z",
        "url": "https://www.livechatinc.com/tour",
        "title": "LiveChat - Tour"
      }
    ]
  },
  "fields": {
    "custom field name": "custom field value"
  },
  "statistics": {
    "chats_count": 3,
    "threads_count": 9,
    "visits_count": 5
  },
  "__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",
  "created_at": "2017-10-11T15:19:21.010200Z",
  "present": true, // optional, applies only to customer located in chat object
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.Notes
agent_last_event_created_atoptional
avataroptional
customer_last_event_created_atoptional
created_atoptional
emailoptional
fieldsoptionalIs not present when the chat is archived.
nameoptional
events_seen_up_tooptionalRFC 3339 datetime string
last_visitoptional
presentoptional
statisticsoptional

Other common structures

Apart from Events and Users, there are also other common data structures you might work with. Those are:

Access

Sample Access data structure
Copied!
{
  "access": {
    "group_ids": [1, 2]
  }
}
FieldReq./Opt.Note
group_idsrequiredgroup 0 means that all agents can see it.

Chats

Sample Chat data structure
Copied!
{
  "id": "PJ0MRSHTDG",
  "users": [
    // array of "User" objects
  ],
  "threads": [
    // optional
    // "Thread" object
  ],
  "threads_summary": [
    {
      "thread_id": "K600PKZON8",
      "order": 129846129847
    },
    {
      "thread_id": "K600PKZON8",
      "order": 129846129848
    }
  ],
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": true
}
FieldReq./Opt.
propertiesoptional
accessoptional

Chat summaries

Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread object, while Chat summary includes last_thread_summary and last_event_per_type.

Sample Chat summary data structure
Copied!
{
  "id": "PJ0MRSHTDG",
  "users": [
    // array of "User" objects
  ],
  "last_event_per_type": {
    // last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_order": 3,
      "event": {
        // "restricted_access": true
        // or
        // "Event > Message" object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON6",
      "thread_order": 1,
      "event": {
        // "restricted_access": true
        // or
        // "Event > System message" object
      }
    }
    // ...
  },
  "last_thread_summary": {
    "id": "K600PKZON8",
    "order": 3,
    "timestamp": 1473433500,
    "user_ids": ["agent1@example.com"],
    "properites": {
      // "Properites" object
    },
    "tags": ["bug_report"]
  },
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": false
}

Form fields

A component of the Filled form event.

FieldRequiredData typeNotes
fieldsyesarray of objectsThe fields a form contains.
typeyesstringPossible values: checkbox, email, name, question, textarea, group_chooser, radio, select
idyesstringField id, for all field types
labelyesstringField label; for all field types
answeryesanyFor all field types
answer.idyesstringAnswer id; for all field types
answer.labelyesstringAnswer label; for all field types
answer.group_idyesnumberFor group_chooser
Response
Copied!
{
	"fields": [{
		"type": "name",
		"id": "154417206262603539",
		"label": "Your name",
		"answer": "John Doe"
	}, {
		"type": "email",
		"id": "154417206262601584",
		"label": "Your email",
		"answer": "customer1@example.com"
	}, {
		"type": "radio",
		"id": "154417206262602571",
		"label": "Chat purpose",
		"answer": {
				"id": "0",
				"label": "Support"
		}
	}, {
		"type": "checkbox",
		"id": "154417206262604640",
		"label": "Company industry",
		"answers": [{
			"id": "0"
			"label": "automotive"
		}, {
			"id": "1"
			"label": "it"
		}]
	}, {
		"type": "group_chooser",
		"id": "154417206262605324",
		"label": "Choose department",
		"answer": {
			"group_id": 1,
			"label": "Marketing"
		}
	}]
}

Properties

Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.

Sample Properties data structure
Copied!
{
  "properties": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure
Copied!
{
  "id": "K600PKZON8",
  "timestamp": 1473433500,
  "active": true,
  "user_ids": ["agent1@example.com"],
  "restricted_access": true,
  "events": [
    // array of "Event" objects
  ],
  "order": 112057129857,
  "properties": {
    // "Properties" object
  },
  "access": {
    // "Access" object
  }
}
FieldReq./Opt.Note
accessoptional-
activerequiredPossible values: true (thread is still active) or false(thread no longer active)
eventsoptionalDoesn't exists if restricted_access is true.
propertiesoptional-
restricted_accessoptional-

Methods

Web API actions can generate webhooks, as well as pushes. However, pushes can be delivered only in the websocket transport. If you want to be notified about emitted events with webhooks, you need to register them first.

HTTP methodThe API enpoint
POSThttps://api.livechatinc.com/v3.1/agent/action/<action>
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-RegionfraRequired for a license from Europe. More info...
X-Author-Id<bot_agent_id>Valid only for Bot Agents
X-API-VersionAPI version, for example 3.1You don't need this header if you specify API version in the URL.
GENERAL WEB API REQUEST FORMAT
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.1/agent/action/<action> \
  -H 'Content-Type: <content-type>' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
        // payload
      }'

Available methods

Run in Postman

Chats

Get Chats Summary

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

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/get_chats_summary
Required scopeschats--all:ro chats--access:ro chats--my:ro
RTM API equivalentget_chats_summary
Webhook-
Request
ParameterRequiredTypeNotes
filtersNoobjectMustn't change between requests for subsequent pages. Otherwise, the behavior is undefined.
filters.include_activeNoboolDefines if the returned chat summary includes active chats; default: true.
filters.group_idsNoarrayArray of group IDs.
filters.properties.<namespace>.<name>.<filter_type>Noany
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
ParameterData typeNotes
found_chatsnumberAn estimated number. The real number of found chats can slightly differ.
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.1/agent/action/get_chats_summary \
  -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_order": 1,
                    "event": {
                        "id": "Q298LUVPRH_1",
                        "created_at": "2019-12-09T12:01:18.909000Z",
                        "recipients": "all",
                        "type": "message",
                        "text": "hello world",
                        "author_id": "5ae8b076-03b0-43db-44f9-b95f8ead62e4"
                    }
                },
                "system_message": {
                    "thread_id": "K600PKZON8",
                    "thread_order": 1,
                    "event": {
                      // "System message" event
                    }
                }
            },
            "users": [
                {
                  // "Customer" user object
                },
                {
                  // "Agent" user object
                }
            ],
            "last_thread_summary": {
                "id": "K600PKZON8",
                "timestamp": 1575892853,
                "user_ids": [
                    "5ae8b076-03b0-43db-44f9-b95f8ead62e4",
                    "customer1@example.com"
                ],
                "order": 1,
                "properties": {
                  // "Properties" object
                },
                "active": true,
                "access": {
                    "group_ids": [0]
                }
            },
            "properties": {
              // "Properties" object
            },
            "access": {
                "group_ids": [0]
            },
            "order": 1575892853242000,
            "is_followed": true
            }
        ],
        "found_chats": 4
}

Get Chat Threads Summary

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/get_chat_threads_summary
Required scopeschats--all:ro chats--access:ro chats--my:ro
RTM API equivalentget_chat_threads_summary
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
orderNostringPossible values: asc - oldest chats first and desc - newest chats first (default).
limitNonumberDefault: 10, maximum: 100
page_idNostring
Response
ParameterData typeNotes
found_threadsnumberNumber of threads in a chat
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.1/agent/action/get_chat_threads_summary \
 -H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PWJ8Y4THAV"
    }'
Response
Copied!
{
  "threads_summary": [
    {
      "id": "PT039ES4OG",
      "order": 2,
      "events_count": 2
    },
    {
      "id": "PT039DS6IP",
      "order": 1,
      "events_count": 17
    }
  ],
  "found_threads": 7,
  "next_page_id": "MTUxNzM5ODEzMTQ5Ng==", // optional
  "previous_page_id": "MTUxNzM5ODEzMTQ5Nw==" // optional
}

Get Chat Threads

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

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/get_chat_threads
Required scopeschats--all:ro chats--access:ro
RTM API equivalentget_chat_threads
Webhook-
Request
ParameterRequiredData type
chat_idYesstring
thread_idsNoarray
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.1/agent/action/get_chat_threads \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PWJ8Y4THAV"
      }'
Response
Copied!
{
    "chat": {
        "id": "PWJ8Y4THAV",
        "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": "agent1@example.com",
                "name": "Agent Name",
                "email": "agent1@example.com",
                "type": "agent",
                "present": true,
                "avatar": "https://example.com/avatar.jpg"
            }
        ],
        "threads_summary": [
            {
                "thread_id": "Q20N9CKRX2",
                "order": 1
            }
        ],
        "properties": {
          // "Property" object
        },
        "access": {
            "group_ids": [0]
        },
        "is_followed": true
    }
}

Get 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.1/agent/action/get_archives
Required scopeschats--all:ro chats--access:ro
RTM API equivalentget_archives
Webhook-
Request
ParameterRequiredData typeNotes
filtersNoobject
filters.queryNostring
filters.date_fromNostringYYYY-MM-DD format
filters.date_toNostringYYYY-MM-DD format
filters.agent_idsNoarrayArray of agent IDs
filters.thread_idsNoarrayArray of thread IDs. Cannot be used with other filters or pagination; max array size: 20.
filters.group_idsNoarrayArray of group IDs
filters.properties.<namespace>.<name>.<filter_type>Noany* described below
filters.tags.<filter_type>Noany
filters.sales.<filter_type>Noany
filters.goals.<filter_type>Noany
filters.surveys.<survey>Noarray** described below
paginationNoobject
pagination.pageNonumberDefault: 1, min: 1, max: 1000
pagination.limitNonumberDefault: 25, min: 0, max: 100

*)

sort_order can take the following values:

  • asc - the oldest chats first
  • desc - the newest chats first

<filter_type> can take the following values:

  • exists (bool)
  • values (type[] - an array with aspecific 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.

**) <survey> contains the following fields:

  • type (string) - allowed values: pre_chat, post_chat
  • answer_id (string)
REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.1/agent/action/get_archives \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "thread_ids": ["K600PKZON8"]
    }
  }'
Response
Copied!
{
  "chats": [
    {
      "id": "PJ0MRSHTDG",
      "users": [
        {
          "id": "smith@example.com",
          "name": "Agent Smith",
          "email": "smith@example.com",
          "type": "agent",
          "present": true,
          "avatar": "https://cdn.livechatinc.com/cloud/?uri=avatar.jpg"
        }
      ],
      "thread": {
        "id": "K600PKZON8",
        "timestamp": 1590666298,
        "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": {
                  "value": "property_value"
                }
              }
            },
            "text": "Hello, how can I help you?",
            "author_id": "smith@example.com"
          }
        ],
        "order": 1,
        "properties": {
          "0805e283233042b37f460ed8fbf22160": {
            "thread_property": {
              "value": "property_value"
            }
          }
        },
        "access": {
          "group_ids": [
            0
          ]
        }
      },
      "properties": {
        "0805e283233042b37f460ed8fbf22160": {
          "chat_property": {
            "value": "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.

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

*) 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.usersNoarrayThe list of existing users. Only one user is allowed (type customer).
chat.threadNoobject
chat.thread.eventsNoarrayThe list of initial chat events.
chat.thread.propertiesNoobject
continuousNoboolStarts chat as continuous (online group is not required); default: false.
Response
ParameterData 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.1/agent/action/start_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "PGDGHT5G"
}

Activate Chat

Restarts an archived chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/activate_chat
Required scopes *chats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentactivate_chat
Webhookincoming_chat_thread

*) 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 activated.
chat.accessNoobjectChat access to set, default: all agents.
chat.propertiesNoobjectInitial chat properties
chat.usersNoarrayThe list of existing users. Only one user is allowed (type customer).
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial chat thread properties
continuousNoboolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Response
ParameterData typeNotes
thread_idstring
event_ids[]stringReturned only when the chat was activated 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.1/agent/action/activate_chat \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat": {
          "id": "PWJ8Y4THAV"
          }
      }'
Response
Copied!
{
  "thread_id": "Z8AGR5OUW"
}

Close Thread

Closes a thread. Sending messages to this thread will no longer be possible.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/close_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentclose_thread
Webhookthread_closed
Request
ParameterRequiredData type
chat_idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
  https://api.livechatinc.com/v3.1/agent/action/close_thread \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_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.1/agent/action/follow_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentfollow_chat
Webhookincoming_chat_thread*

*) It won't be sent when the requester already follows the chat or is the chat member.

Request
ParameterRequiredData type
chat_idYesstring
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/follow_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_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.1/agent/action/unfollow_chat
Required scopes-
RTM API equivalentunfollow_chat
Webhook-
Request
ParameterRequiredData type
chat_idYesstring
Response

No response payload (200 OK).

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

Chat access

Grant Access

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

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/grant_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentgrant_access
Webhookaccess_granted
Request
ParameterRequiredData ypeNotes
resourceYesstringchat or customer
idYesstringResource Id
accessYesobjectThe entity that is granted access to the specified resource
access.typeYesstringgroup
access.idYesnumber
Response

No response payload (200 OK).

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

Revoke Access

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/revoke_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentrevoke_access
Webhookaccess_revoked
Request
ParameterRequiredData typeNotes
resourceYesstringchat or customer
idYesstringResource Id
accessYesobjectThe entity that loses access to the specified resource
access.typeYesstringgroup
access.idYesnumber
Response

No response payload (200 OK).

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

Set Access

Gives access to a new resource overwriting the existing ones.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/set_access
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentset_access
Webhookaccess_set
Request
Request objectRequiredTypeNotes
resourceYesstringchat or customer
idYesstringresource id
accessYesobjectThe entity that is given access to the specified resource
access.typeYesstringgroup
access.idYesnumber
Response

No response payload (200 OK).

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

Transfer Chat

Transfers a chat to an Agent or a group.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/transfer_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalenttransfer_chat
Webhook-
Request
ParameterRequiredData ypeNotes
chat_idYesstringResource Id
targetNoobjectIf missing, 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.1/agent/action/transfer_chat \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PWF6BACIKO",
   "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.1/agent/action/add_user_to_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentadd_user_to_chat
Webhookchat_user_added
Request
Request objectRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible values: agent or customer
Response

No response payload (200 OK).

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

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.1/agent/action/remove_user_from_chat
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentremove_user_from_chat
Webhookchat_user_removed

Request payload

Request objectRequiredTypeNotes
chat_idYesstring
user_idYesstring
user_typeYesstringPossible values are agent or customer
Response

No response payload (200 OK).

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

Events

Send Event

Sends an Event object. Use this method to send a message by specifing 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 chat_user_added). Sample use case: a Bot Agent that sends messages visible to all chat participants without actually joining the chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/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
attach_to_last_threadNoboolIf true, adds an event to last (inactive) thread. Otherwise, it doesn't creates a new one; default false.
Response
ParameterData type
event_idstring
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/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.1/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.1/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.1/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.1/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.1/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
chat_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.1/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
    "chat_id": "PW94SJTGW6",
    "properties": {
        "bb9e5b2f1ab480e4a715977b7b1b4279": {
            "score": 10,
            "comment": "Thank you!"
            }
        }
    }'

Delete Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/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
chat_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.1/agent/action/delete_chat_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "chat_id": "PW94SJTGW6",
      "properties": {
          "bb9e5b2f1ab480e4a715977b7b1b4279": [
              "score",
              "comment"
              ]
          }
      }'

Update Chat Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/update_chat_thread_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentupdate_chat_thread_properties
Webhookchat_thread_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.1/agent/action/update_chat_thread_properties \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "chat_id": "PW94SJTGW6",
        "thread_id": "K600PKZON8",
        "properties": {
            "bb9e5b2f1ab480e4a715977b7b1b4279": {
                "score": 10,
                "comment": "Thank you!"
              }
          }
      }'

Delete Chat Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/delete_chat_thread_properties
Required scopeschats.conversation--all:rw chats.conversation--access:rw chats.conversation--my:rw
RTM API equivalentdelete_chat_thread_properties
Webhookchat_thread_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.
propertiesYesobjectChat thread properties to delete.
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/delete_chat_thread_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PW94SJTGW6",
   "thread_id": "K600PKZON8",
   "properties": {
       "bb9e5b2f1ab480e4a715977b7b1b4279": [
           "score",
           "comment"
           ]
       }
   }'

Update Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/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.1/agent/action/update_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PW94SJTGW6",
   "thread_id": "K600PKZON8",
   "event_id": "2_EW2WQSA8",
   "properties": {
       "bb9e5b2f1ab480e4a715977b7b1b4279": {
           "score": 10,
           "comment": "Thank you!"
           }
       }
   }'

Delete Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/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.1/agent/action/delete_event_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "chat_id": "PW94SJTGW6",
   "thread_id": "K600PKZON8",
   "event_id": "2_EW2WQSA8",
   "properties": {
       "bb9e5b2f1ab480e4a715977b7b1b4279": {
           "rating": [
               "score",
               "comment"
               ]
           }
       }
   }'

Thread tags

Tag Chat Thread

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/tag_chat_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalenttag_chat_thread
Webhookchat_thread_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
Response

No response payload (200 OK).

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

Untag Chat Thread

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/untag_chat_thread
Required scopeschats--all:rw chats--access:rw chats--my:rw
RTM API equivalentuntag_chat_thread
Webhookchat_thread_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
Response

No response payload (200 OK).

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

Customers

Get Customers

It returns the list of Customers.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/get_customers
Required scopescustomers:ro
RTM API equivalentget_customers
Webhook-
Request

All parameters are optional.

ParameterData typeNotes
page_idstring
limitnumberDefault: 10, maximum: 100
order *stringDefault: desc
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

*)

order can take the following values:

  • asc - oldest customers first
  • desc - newest customers first

**)

<string_filter_type> can take the following values :

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

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
ParameterData 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.1/agent/action/get_customers \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
  "customers": [
    // array of "User > Customer" objects
  ],
  "total_customers": 2340,
  "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.1/agent/action/create_customer
Required scopescustomers:rw
RTM API equivalentcreate_customer
Webhookcustomer_created
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar
fieldsNoobjectA map in the "key": "value" format
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/create_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{}'
Response
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}

Update Customer

Updates Customer's properties.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/update_customer
Required scopescustomers:rw
RTM API equivalentupdate_customer
Webhook-
Request
ParameterRequiredData typeNotes
customer_idYesstringUUID v4 format is required
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar
fieldsNoobjectA map in the "key": "value" format

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

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/update_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "customer_id": "646d53b8-ba76-48bf-7ef1-f6d61ec4ec44",
   "name": "John Doe"
   }'
Response
Copied!
{
  // "User > Customer" object
}

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.1/agent/action/ban_customer
Required scopescustomers.ban:rw
RTM API equivalentban_customer
Webhook-
Request
ParameterRequiredData type
customer_idYesstring
banYesobject
ban.daysYesnumber
Response

No response payload (200 OK).

REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.1/agent/action/ban_customer \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
   "customer_id": "3cd19fff-f852-4402-59ce-ebd03af3f15a",
   "ban": {
       "days": 3
       }
   }'

Status

Update Agent

Updates Agent's properties.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/agent/action/update_agent
Required scopesagents--my:rw agents--all:rw
RTM API equivalentupdate_agent
Webhook-
Request
ParameterRequiredData typeNotes
agent_idNostringThe current Agent is used by default.
routing_statusNostringPossible values: accepting_chats, not_accepting_chats
Response

No response payload (200 OK).

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

Other

Mark Events as Seen

Specifics
Method URLhttps://api.livechatinc.com/v3.1/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.1/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.1/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.1/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.1/agent/action/multicast
Required scopesmulticast:rw
RTM API equivalentmulticast
Webhook-
Request
ParameterRequiredData typeNotes
scopesYesobject*
contentYesanyA JSON message to be sent
typeNostringMulticast message type

*) scopes 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 scopes type (agents.all, agents.ids, agents.groups, customers.ids) is required.

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

Webhooks

Here's what you need to know about webhooks:

  • Webhooks notify you when specific events occur.
  • They can be generated by both Web and RTM API actions.
  • When using RTM API, you can be also notified about events with pushes.
  • Webhooks and pushes have similar payloads.
  • To receive webhooks, you need to register them first. You can do it via the Configuration API. Refer to this document to see the list of available webhooks, as well as sample payloads.

Errors

General error format
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.
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.
misdirected_requestWrong regionClient's request should be performed to another region. The correct region is returned in the optional data object. It helps to figure out where the client should be connected.
request_timeoutRequest timed outTimeout threshold is 15 seconds.
unsupported_versionUnsupported versionUnsupported protocol version.
validationWrong format of request
wrong_product_versionWrong product versionLicense is not LiveChat 3 (probably still LiveChat 2).
too_many_requestsToo many requestsThe request's rate limit was exceeded. It'll be unblocked automatically after some time.

Contact us

If you found a bug or a typo, you can let us know directly on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@livechatinc.com. We'll be happy to hear from you!