Web API Reference 4 minutes reading time
This document describes the Customer Chat Web API v3.1 . This is the latest stable version recommended for the production use. Read more about versionig...
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.
If you're wondering which API to use - Customer 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 Customer Chat RTM API
Customer authentication is handled by access tokens. Find out how to get an access token from Customer authorization flow . Take note it's not the same token you would you for the Agent Chat or Configuration API.
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.
You can find all the requests from the Customer 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.
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 :
The File event informs about a file being uploaded.
Field Required Data type Notes custom_idno stringtypeyes stringfilepropertiesno objectProperties urlyes stringHas to point to the LiveChat CDN. It's recommended to use the URL returned by upload_file
Field Returned Notes idalways custom_idoptionally created_atalways Date & time format with a resolution of microseconds, UTC string. typealways author_idalways propertiesoptionally namealways urlalways thumbnail_url, thumbnail2x_urlonly for images content_typealways size, width, heightonly for images
Sample File in response
{
"id" : "0affb00a-82d6-4e07-ae61-56ba5c36f743" ,
"custom_id" : "31-0C-1C-07-DB-16" ,
"created_at" : "2017-10-12T15:19:21.010200Z" ,
"type" : "file" ,
"author_id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"properties" : {
"Properties" object
} ,
"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
} The Filled form event contains data from a form (prechat or postchat survey).
Field Required Data type Notes custom_idno stringtypeyes stringfilled_formpropertiesno objectProperties form_idyes stringfieldsyes arrayThe fields a form contains. See form fields for details.
Field Returned Notes idalways custom_idoptionally created_atalways Date & time format with a resolution of microseconds, UTC string. typealways author_idalways propertiesoptionally form_idalways fieldsalways An array of form fields
Sample Filled form in response
{
"id" : "0affb00a-82d6-4e07-ae61-56ba5c36f743" ,
"custom_id" : "31-0C-1C-07-DB-16" ,
"created_at" : "2017-10-12T15:19:21.010200Z" ,
"type" : "filled_form" ,
"author_id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"properties" : {
"Properties" object
} ,
"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 event contains text message to other chat users.
Field Required Data type Notes custom_idno stringtextyes stringMax. 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. typeyes stringmessagepropertiesno objectProperties postbackno objectIndicates that the message event was generated in response to a rich message event. postback.idyes stringID of the postback from the rich message event. postback.thread_idyes stringID of the thread with the rich message event. postback.event_idyes stringID of the rich message event. postback.typeno stringShould be used together with postback.value (when one of them is present, the other is required). postback.valueno stringShould be used together with postback.type (when one of them is present, the other is required).
Field Returned Notes idalways custom_idoptionally created_atalways Date & time format with a resolution of microseconds, UTC string. typealways messageauthor_idalways textalways postbackoptionally Appears in a message only when triggered by a rich message. postback.idalways postback.thread_idalways postback.event_idalways postback.typeoptionally Appears only if postback.value is present. postback.valueoptionally Appears only if postback.type is present. propertiesoptionally Properties
Sample Message in response
{
"id" : "0affb00a-82d6-4e07-ae61-56ba5c36f743" ,
"custom_id" : "31-0C-1C-07-DB-16" ,
"created_at" : "2017-10-12T15:19:21.010200Z" ,
"type" : "message" ,
"author_id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"text" : "hello there" ,
"postback" : {
"id" : "action_call" ,
"thread_id" : "K600PKZON8" ,
"event_id" : "75a90b82-e6a4-4ded-b3eb-cb531741ee0d" ,
"type" : "phone" ,
"value" : "790034890"
} ,
"properties" : {
"Properties" object
}
} Rich message (RM) event contains a rich message data structure. Read more about rich messages.
Field Required Data type Notes custom_idno stringYou can give your RM a custom ID. typeyes stringEvent type: rich_message propertiesno objectThe properties data structure template_idyes stringDefines how every Rich Message will be presented. Values: cards, sticker, or quick_replies. elementsno arrayCan contain up to 10 element objects. elements.titleyes stringDisplays formatted text on RMs. elements.subtitleyes stringDisplays formatted text on RMs. elements.imageyes imageDisplays images on RMs. Required param: url; Optional params: name, content_type, size, width, height. elements.buttonsno arrayDisplays buttons. Can contain up to 11 button objects. elements.buttons.textyes stringText displayed on a button. elements.buttons.typeyes arrayDefines 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.valueyes stringShould be used together with elements.buttons.type. elements.buttons.webview_heightyes stringRequired only for the webview buttontype. Possible values: compact, full, tall. elements.buttons.postback_idyes stringA description of the sent action. Describes the action sent via send_rich_message_postback. More... elements.buttons.user_idsyes arrayDescribes users that sent the postback with "toggled": true.
Field Returned Notes idalways Generated server-side custom_idoptionally typealways author_idalways Generated server-side created_atalways Date & time format with a resolution of microseconds, UTC string. Generated server-side. propertiesoptionally template_idalways elementsoptionally elements.titlealways elements.subtitlealways elements.imagealways elements.buttonsoptionally elements.buttons.textalways elements.buttons.typealways elements.buttons.valuealways elements.buttons.webview_heightalways Unless button type is different than webview. elements.buttons.postback_idalways elements.buttons.user_idsalways
Sample Rich message event
{
"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" ,
"properties" : {
"Properties" object
} ,
"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 event is an event with customizable payload.
Field Required Data type Notes custom_idno stringYou can give the event a custom ID. typeyes stringEvent type: custom contentno objectThe content you define propertiesno objectThe properties data structure
Field Returned Notes idalways Generated server-side custom_idoptionally typealways author_idalways Generated server-side created_atalways Date & time format with a resolution of microseconds, UTC string; generated server-side contentoptionally propertiesoptionally
Sample Custom event
{
"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"
}
} ,
"properties" : {
"Properties" object
}
} System message event is a native system event sent in specific situations.
Field Required Data type Notes custom_idno stringYou can give the system message a custom ID. typeyes stringsystem_messagetextno stringText displayed to recipients system_message_typeyes stringSystem message type text_varsno objectVariables used in the text
Field Returned Notes idalways Generated server-side custom_idoptionally typealways created_atalways Date & time format with a resolution of microseconds, UTC string; generated server-side textoptionally system_message_typealways
Sample System message event
{
"id" : "0affb00a-82d6-4e07-ae61-56ba5c36f743" ,
"custom_id" : "31-0C-1C-07-DB-16" ,
"created_at" : "2017-10-12T15:19:21.010200Z" ,
"type" : "system_message" ,
"text" : "hello there" ,
"system_message_type" : "routing.assigned" ,
"text_vars" : {
"agent" : "John Doe"
}
} Here's the list of all system messages you might come across:
Content Generated when %initiator% added %agent% to the chat Agent was added to chat via the add_user_to_chat request and is not the first Agent in that chat.
Content Generated when %initiator% removed %agent% from the chat Agent was removed from chat via the remove_user_from_chat request.
Content Generated when %customer% left the chat Chat ended after Customer left the website.
Content Generated when %initiator% transferred the chat to %targets% Chat was transferred via the transfer_chat request.
Content Generated when %initiator% added %customer% to the chat Customer was added to chat via the add_user_to_chat request.
Content Generated when Chat archived because customer was banned by %agent% for %duration% day(s) Chat ended becaus Customer was banned via the ban_customer request.
Content Generated when %initiator% removed %customer% from the chat Customer was removed from chat via the remove_user_from_chat request.
Content Generated when %agent% archived the chat Agent closed chat via the close_thread request.
Content Generated when %customer% archived the chat Customer closed chat via the close_thread request.
Content Generated when %customer% left the following comment: %comment% Chat was commented by Customer.
Content Generated when %customer% rated the chat as %score% Chat was rated by Customer.
Content Generated when %customer% canceled the chat rating Chat rating was cancelled by Customer.
Content Generated when The chat was closed because %agent% account had been deleted Chat was archived after Agent was removed from the license. No other Agent could be selected, and queues were disabled.
Content Generated when The chat was closed because %agent% had lost internet connection Chat was archived after Agent unexpectedly lost connection. No other Agent could be selected, and queues were disabled.
Content Generated when Chat archived due to %duration% minutes of inactivity No new messages were posted for an extended amount of time.
Content Generated when Chat archived due to no available agents No Agent could be selected after chat was placed in the queue.
Content Generated when The chat was closed Chat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.
Content Generated when The chat was closed because %agent% had been remotely signed out Chat was archived after an Agent was logged out. No other Agent could be selected and queues were disabled.
Content Generated when The chat was closed because %agent% had signed out Chat was archived after Agent logged out. No other Agent could be selected, and queues were disabled.
Content Generated when Chat assigned to %agent_added% because %agent_removed% account had been deleted Chat was assigned to a new Agent after the previous one was removed from the license.
Content Generated when Chat assigned to %agent_added% because %agent_removed% had lost internet connection Chat was assigned to a new Agent after the previous one unexpectedly lost connection.
Content Generated when Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutes Chat was assigned to a new Agent after the previous one failed to response in a timely manner.
Content Generated when The chat was closed Chat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.
Content Generated when Chat assigned to %agent_added% because %agent_removed% had been remotely signed out Chat was assigned to a new Agent after the previous one was logged out.
Content Generated when Chat assigned to %agent_added% because %agent_removed% had signed out Chat was assigned to a new Agent after the previous one logged out.
Content Generated when Customer was queued because %agent% account has been deleted Chat was queued after Agent was removed from the license.
Content Generated when Customer was queued because %agent% had lost internet connection Chat was queued after Agent unexpectedly lost connection.
Content Generated when Chat is unassigned Chat was queued after Agent was removed from chat for other reasons.
Content Generated when Customer was queued because %agent% had been remotely signed out Chat was queued after Agent was logged out.
Content Generated when Customer was queued because %agent% had signed out Chat was queued after Agent logged out.
Content Generated when Chat archived License was moved to another lc_serv instance while there were still active chats.
Content Generated when %customer% requested the chat transcript to be sent to %email% Customer enables transcript.
Users are another important data structure. Within this data structure type, we can distinguish:
Sample Customer data structure
{
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"type" : "customer" ,
"name" : "John Smith" ,
"email" : "customer1@example.com" ,
"avatar" : "https://example.com/avatars/1.jpg" ,
"fields" : {
"custom field name" : "custom field value"
} ,
"present" : true ,
"events_seen_up_to" : "2017-10-12T15:19:21.010200Z"
} Field Req./Opt. avataroptional emailoptional nameoptional fieldsoptional
Sample Agent data structure
{
"id" : "agent1@example.com" ,
"type" : "agent" ,
"name" : "Support Team" ,
"avatar" : "cdn.livechatinc.com/avatars/1.png" ,
"present" : true ,
"events_seen_up_to" : "2017-10-12T15:19:21.010200Z"
} Apart from Events and Users , there are also other common data structures you might work with. Those are:
Sample Access data structure
{
"access" : {
"group_ids" : [ 1 , 2 ]
}
} Field Req./Opt. Note group_idsrequired group 0 means that all agents can see it.
Sample Chat data structure
{
"id" : "PJ0MRSHTDG" ,
"users" : [
"User" objects
] ,
"threads" : [
"Thread" object
] ,
"threads_summary" : [
{
"thread_id" : "K600PKZON8" ,
"order" : 129846129847
} ,
{
"thread_id" : "K600PKZON8" ,
"order" : 129846129848
}
] ,
"properites" : {
"Properites" object
} ,
"access" : {
"Access" object
} ,
"is_followed" : true
} Field Req./Opt. Note propertiesoptional accessoptional
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
{
"id" : "PJ0MRSHTDG" ,
"users" : [
"User" objects
] ,
"last_event_per_type" : {
"message" : {
"thread_id" : "K600PKZON8" ,
"thread_order" : 3 ,
"event" : {
"restricted_access" : true
"Event > Message" object
}
} ,
"system_message" : {
"thread_id" : "K600PKZON6" ,
"thread_order" : 1 ,
"event" : {
"restricted_access" : true
"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
} A component of the Filled form event.
Field Required Data type Notes fieldsyes array of objectsThe fields a form contains. typeyes stringPossible values: checkbox, email, name, question, textarea, group_chooser, radio, select idyes stringField id, for all field types labelyes stringField label; for all field types answeryes anyFor all field types answer.idyes stringAnswer id; for all field types answer.labelyes stringAnswer label; for all field types answer.group_idyes numberFor group_chooser
Response
{
"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 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
{
"properties" : {
"rating" : {
"score" : {
"value" : 1
} ,
"comment" : {
"value" : "rated good!"
}
} ,
"routing" : {
"idle" : {
"value" : false
}
}
}
} Sample Thread data structure
{
"id" : "K600PKZON8" ,
"timestamp" : 1473433500 ,
"active" : true ,
"user_ids" : [ "agent1@example.com" ] ,
"restricted_access" : true ,
"events" : [
"Event" objects
] ,
"order" : 112057129857 ,
"properties" : {
"Properties" object
} ,
"access" : {
"Access" object
}
} Field Req./Opt. Note accessoptional - activerequired Possible values: true (thread is still active) or false(thread no longer active). eventsoptional Doesn't exists if restricted_access is true. propertiesoptional - restricted_accessoptional -
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 method The API endpoint POSThttps://api.livechatinc.com/v3.1/customer/action/<action>
Header Value Notes Content-Typemultipart/form-data; boundary=<boundary>Valid for the upload_file method Content-Typeapplication/jsonValid for every method except for upload_file AuthorizationBearer <token>Customer access token. It's not the same token you would use for the Agent Chat or Configuration API. Read more... X-RegionfraRequired for a license from Europe. More info... X-API-VersionAPI version, for example 3.1 You don't need this header if you specify API version in the URL.
Every request to Customer Chat API needs to have the following query string parameters:
Required parameter Data type Notes license_idintegerLiveChat account ID
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
// payload
}'
It returns summaries of the chats a Customer participated in.
Method URL https://api.livechatinc.com/v3.1/customer/action/get_chats_summaryRTM API equivalent get_chats_summaryWebhook -
Parameter Required Type Notes offsetNo numberDefault: 0, maximum: 100 limitNo numberDefault: 10, maximum: 25
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/get_chats_summary?license_id= < license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}' Response
{
"request_id" : "<request_id>" ,
"action" : "get_chats_summary" ,
"type" : "response" ,
"success" : true ,
"payload" : {
"chats_summary" : [
{
"id" : "PJ0MRSHTDG" ,
"order" : 1575892853242000 ,
"last_thread_id" : "K600PKZON8" ,
"last_event_per_type" : {
"message" : {
"thread_id" : "K600PKZON9" ,
"thread_order" : 1 ,
"event" : {
"id" : "Q298LUVPRH_1" ,
"created_at" : "2019-12-09T12:01:18.909000Z" ,
"type" : "message" ,
"text" : "hello world" ,
"author_id" : "b7eff798-f8df-4364-8059-649c35c9ed0c"
}
}
} ,
"users" : [
{
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"type" : "customer" ,
"present" : true
} ,
{
"id" : "d5eff798-f8df-4364-8059-649c35c9ed0c" ,
"name" : "Agent Name" ,
"type" : "agent" ,
"present" : true ,
"avatar" : "https://example.com/avatar.png" ,
"job_title" : "Support Agent"
}
] ,
"access" : {
"group_ids" : [ 0 ]
} ,
"properties" : {
"Properties" object
}
} ,
"active" : true
}
] ,
"total_chats" : 1
}
} Method URL https://api.livechatinc.com/v3.1/customer/action/get_chat_threads_summaryRTM API equivalent get_chat_threads_summaryWebhook -
Parameter Required Data type Notes chat_idYes stringoffsetNo numberDefault: 0 limitNo numberDefault: 25, maximum: 100
Parameter Notes threads_summarySorted descendingly by order.
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/get_chat_threads_summary?license_id= < license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG"
}' Response
{
"threads_summary" : [
{
"id" : "Q298LUVPRH" ,
"order" : 1 ,
"total_events" : 1 ,
"active" : true
}
] ,
"total_threads" : 1
} Method URL https://api.livechatinc.com/v3.1/customer/action/get_chat_threadsRTM API equivalent get_chat_threadsWebhook -
Parameter Required Data type chat_idYes stringthread_idsYes array
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/get_chat_threads?license_id= < license_id> \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"thread_ids": ["K600PKZON8"]
}' Response
{
"chat" : {
"id" : "PJ0MRSHTDG" ,
"order" : 1576569422 ,
"threads" : [
{
"id" : "K600PKZON8" ,
"active" : true ,
"user_ids" : [
"b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"bbb67d600796e9f277e360e842418833"
] ,
"events" : [
{
"id" : "Q20N9CKRX2_1" ,
"created_at" : "2019-12-17T07:57:41.512000Z" ,
"type" : "message" ,
"text" : "Hello" ,
"author_id" : "bbb67d600796e9f277e360e842418833"
}
] ,
"order" : 1 ,
"properties" : {
"Property" object
} ,
"access" : {
"group_ids" : [ 0 ]
}
}
] ,
"users" : [
{
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"type" : "customer" ,
"present" : true
} ,
{
"id" : "bbb67d600796e9f277e360e842418833" ,
"name" : "Agent Name" ,
"type" : "agent" ,
"present" : true ,
"avatar" : "https://example.com/avatar.jpg" ,
"job_title" : "Support Agent"
}
] ,
"access" : {
"group_ids" : [ 0 ]
} ,
"properties" : {
"Property" object
}
}
} Starts a chat.
Parameters Required Data type Notes chatNo objectchat.propertiesNo objectInitial chat properties chat.accessNo objectChat access to set; default: all agents. chat.threadNo objectchat.thread.eventsNo arrayInitial chat events array chat.thread.propertiesNo objectInitial chat thread properties continuousNo boolStarts chat as continuous (online group is not required); default: false.
Parameter Data type Notes chat_idstringthread_idstringevent_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
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/start_chat?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}' Response
{
"chat_id" : "PJ0MRSHTDG" ,
"thread_id" : "PGDGHT5G"
} Used to restart an archived chat.
Request object Required Type Notes chatYes objectchat.idYes stringID of the chat that will be activated. chat.accessNo objectChat access to set; default: all agents. chat.propertiesNo objectInitial chat properties chat.threadNo objectchat.thread.eventsNo arrayInitial chat events array chat.thread.propertiesNo objectInitial chat thread properties continuousNo boolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Parameter Data type Notes thread_idstringevent_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
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/activate_chat?license_id= < license_id> \
-H 'Content-Type: <content-type>' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat": {
"id": "PWLW03ICW7"
}
}' Response
{
"thread_id" : "Z8AGR5OUW"
} Closes the thread. Sending messages to this thread will no longer be possible.
Parameter Required Data type chat_idYes string
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/close_thread?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PWLW03ICW7"
}' Sends an Event object. Use this method to send a message by specifing the Message event type in the request.
Parameters Required Data type Notes chat_idYes stringId of the chat that you to send a message to. eventYes objectThe event object attach_to_last_threadNo boolIf true, adds an event to last (inactive) thread. Otherwise, it doesn't creates a new one; default: false.
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/send_event?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "PWLW03ICW7",
"event": {
"type": "message",
"text": "hello world",
"recipients": "all"
}
}' Response
{
"event_id" : "K600PKZON8"
} 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
Method URL https://api.livechatinc.com/v3.1/customer/action/upload_fileRTM API equivalent - Webhook incoming_event*
*)
incoming_event returns a URL that never expires.
Parameter Required Data type Notes fileYes binaryMaximum size: 10MB
REQUEST
curl -X POST \
https://api.livechatinc.com/v3.1/customer/action/upload_file?license_id= < license_id> \
-H 'Authorization: Bearer <customer_access_token>' \
-H 'Content-Type: multipart/form-data; boundary=--------------------------210197025774705439685896' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file = @/Users/MyAccount/Desktop/image.pngResponse
{
"url" : "https://cdn.livechat-static.com/api/file/lc/att/8948324/45a3581b59a7295145c3825c86ec7ab3/image.png"
} *) incoming_rich_message_postback will be sent only for active threads.
Parameter Required Data type Notes chat_idYes stringevent_idYes stringpostbackYes objectpostback.idYes stringPostback name of the button postback.toggledYes boolPostback toggled; true or false thread_idYes string
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/send_rich_message_postback?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
"postback": {
"id": "Method URL_yes",
"toggled": true
}
}' Sends a sneak peek to a chat.
Method URL https://api.livechatinc.com/v3.1/customer/action/send_sneak_peekRTM API equivalent send_sneak_peekWebhook -
Parameter Required Data type Notes chat_idYes stringId of the chat to send a sneak peek to. sneak_peek_textYes stringSneak peek text
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/send_sneak_peek?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"sneak_peek_text": "hello world"
}' Parameter Required Data type Notes chat_idYes stringId of the chat you to set a property for. propertiesYes objectChat properties to set. You should stick to the general properties format and include namespace , property name and value .
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/update_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}' Parameter Required Data type Notes chat_idYes stringId of the chat you want to delete properties of. propertiesYes objectChat properties to delete.
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/delete_chat_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PW94SJTGW6",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": [
"score",
"comment"
]
}
}' Parameter Required Data type Notes chat_idYes stringId of the chat you want to set properties for. thread_idYes stringId of the thread you want to set properties for. propertiesYes objectChat properties to set.
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/update_chat_thread_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}' Parameter Required Data type Notes chat_idYes stringId of the chat you want to delete the properties of. thread_idYes stringId of the thread you want to delete the properties of. propertiesYes objectChat thread properties to delete.
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/delete_chat_thread_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": [
"score",
"comment"
]
}
}' Parameter Required Data type Notes chat_idYes stringId of the chat you want to set properties for. thread_idYes stringId of the thread you want to set properties for. event_idYes stringId of the event you want to set properties for. propertiesYes objectChat properties to set. You should stick to the general properties format and include namespace , property name and value .
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/update_event_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PW94SJTGW6",
"thread_id": "K600PKZON8",
"event_id": "2_EW2WQSA8",
"properties": {
"bb9e5b2f1ab480e4a715977b7b1b4279": {
"score": 10,
"comment": "Thank you!"
}
}
}' Parameter Required Data type Notes chat_idYes stringId of the chat you want to delete the properties of. thread_idYes stringId of the thread you want to delete the properties of. event_idYes stringId of the event you want to delete the properties of. propertiesYes objectEvent properties to delete. You should stick to the general properties format and include namespace , property name and value .
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/delete_event_properties?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PWLW03ICW7",
"thread_id": "PWNWW5N6A8",
"event_id": "PWNWW5N6A8_1",
"properties": {
"rating": [
"score",
"comment"
]
}
}' Method URL https://api.livechatinc.com/v3.1/customer/action/update_customerRTM API equivalent update_customerWebhook -
Parameter Required Data type Notes nameNo stringemailNo stringavatarNo stringThe URL of the Customer's avatar fieldsNo objectkey: value format
At least one optional parameter needs to be included in the request.
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/update_customer?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"name": "John Doe"
}' Parameter Required Data type Notes fieldsYes objectkey:value format
Users Agent and referrer are updated by default using the browser’s headers.
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/set_customer_fields?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"fields": {
"company_size": "10-100"
}
}' Method URL https://api.livechatinc.com/v3.1/customer/action/get_groups_statusRTM API equivalent get_groups_statusWebhook -
Parameter Required Data type Notes allNo boolIf set to true, you will get statuses of all the groups. groupsNo arrayA table of groups' IDs
One of the optional parameters needs to be included in the request.
No response payload (200 OK).
Group Not FoundIf you send group_id of a group that doesn't exists, the id won't be included in the resposne.
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/get_groups_status?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"all": true
}' Response
{
"groups_status" : {
1 : "online" ,
2 : "offline" ,
3 : "online_for_queue"
}
} Customer can use this method to trigger checking if goals were achieved. Then, Agents receive the information. You should call this method to provide goals parameters for the server when the customers limit is reached. Works only for offline Customers.
Method URL https://api.livechatinc.com/v3.1/customer/action/check_goalsRTM API equivalent - Webhook -
Parameter Required Data type Notes customer_fieldsYes objectkey:value formatgroup_idYes numberpage_urlYes string
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/check_goals?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"page_url": "https://mypage.com",
"customer_fields": {
"field1": "value1"
},
"group_id": 0
}' Returns an empty ticket form of a prechat or postchat survey .
Method URL https://api.livechatinc.com/v3.1/customer/action/get_formRTM API equivalent get_formWebhook -
Parameter Required Data type Notes group_idYes numberId of the group from which you want the form. typeYes stringForm type; possible values: prechat or postchat
Parameter Notes enabledIf enabled: false, the form object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI. headerFor headers; the field has no answer, therefore is not sent in the Filled form event. ratingFor rating; the field has no answer, therefore is not sent in the Filled form event.
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/get_form?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"group_id": 0,
"type": "prechat"
}' Response
{
"form" : {
"id" : "156630109416307809" ,
"fields" : [
{
"id" : "15663010941630615" ,
"type" : "header" ,
"label" : "Welcome to our LiveChat! Please fill in the form below before starting the chat."
} ,
{
"id" : "156630109416307759" ,
"type" : "name" ,
"label" : "Name:" ,
"required" : false
} ,
{
"id" : "15663010941630515" ,
"type" : "email" ,
"label" : "E-mail:" ,
"required" : false
}
]
} ,
"enabled" : true
} Gets the predicted Agent - the one the Customer will chat with when the chat starts. To use this method, the Customer needs to be logged in, which can be done via the login
Method URL https://api.livechatinc.com/v3.1/customer/action/get_predicted_agentRTM API equivalent get_predicted_agentWebhook -
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/get_predicted_agent?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{}' Response
{
"id" : "b7eff798-f8df-4364-8059-649c35c9ed0c" ,
"name" : "Name" ,
"avatar" : "https://example.avatar/example.com" ,
"is_bot" : false ,
"job_title" : "support hero" ,
"type" : "agent"
} It returns the info on a given URL.
Method URL https://api.livechatinc.com/v3.1/customer/action/get_url_detailsRTM API equivalent get_url_detailsWebhook -
Parameter Required Data type Notes urlYes stringValid website URL
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/get_url_details?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"url": "https://livechatinc.com"
}' Response
{
"title" : "LiveChat | Live Chat Software and Help Desk Software" ,
"description" : "LiveChat - premium live chat software and help desk software for business. Over 24 000 companies from 150 countries use LiveChat. Try now, chat for free!" ,
"image_url" : "s3.eu-central-1.amazonaws.com/labs-fraa-livechat-thumbnails/96979c3552cf3fa4ae326086a3048d9354c27324.png" ,
"image_width" : 200 ,
"image_height" : 200 ,
"url" : "https://livechatinc.com"
} Parameter Required Data type Notes chat_idYes stringseen_up_toYes stringRFC 3339 date-time format
No response payload (200 OK).
REQUEST
curl -X POST \
'https://api.livechatinc.com/v3.1/customer/action/mark_events_as_seen?license_id=<license_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <customer_access_token>' \
-d '{
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
}' 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 . General error format
{
"error" : {
"type" : "misdirected_request" ,
"message" : "Wrong region" ,
"data" : {
"region" : "dal"
}
}
} Type Default Message Notes authenticationAuthentication error An invalid or expired access token. authorizationAuthorization error Agent is not allowed to perform the action. customer_bannedCustomer is banned The customer had been banned. entity_too_largeUpload limit exceeded (10MB). Client's request is too large. greeting_not_foundGreeting not found group_not_foundGroup not found group_offlineGroup is offline Thrown in response to Get Predicted Agent . group_unavailableNo agent available for group Thrown in response to Get Predicted Agent . The group is online, but there are no available Agents. groups_offlineGroups offline internalInternal server error license_expiredLicense expired The end of license trial or subcription. license_not_foundLicense not found License with the specified ID doesn't exist. misdirected_requestWrong region Client's request should be performed to another region. It returns the correct region in the optional data object. validationWrong format of request request_timeoutRequest timed out Timeout threshold is 15 seconds. unsupported_versionUnsupported version Unsupported protocol version. wrong_product_versionWrong product version License is not LiveChat 3 (probably still LiveChat 2).
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!
