Web API Reference

4 minutes reading time • last modified 12/05/2019

Introduction

Versioning

This document describes the Customer Chat Web API v3.1.

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 - 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 instead.

Authentication

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.

If a method requires particular authorization 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.

Postman Collection

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.

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

File event informs about a file being uploaded.

FieldReq./Opt.Note
content_typerequiredSupported image types: image/png, image/jpeg, image/gif
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
typerequiredfile
custom_idoptional-
propertiesoptional-
recipientsrequiredPossible values: all (default), agents
urlrequiredHas to point to the LiveChat CDN.It's recommended to use the URL returned by upload_file.
width, height, thumbnail_url, thumbnail2x_urloptionalOnly for images
Sample File event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "file",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "recipients": "all",
  "properties": {
    // "Properties" object
  },
  "name": "image25.png", // generated server-side
  "url": "https://domain.com/image25.png",
  "thumbnail_url": "https://domain.com/thumbnail.png", // generated server-side
  "thumbnail2x_url": "https://domain.com/thumbnail2x.png", // generated server-side
  "content_type": "image/png", // generated server-side
  "size": 123444, // generated server-side
  "width": 640, // generated server-side
  "height": 480 // generated server-side
}

Filled form

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

FieldReq./OptNotes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default), agents
typerequiredfilled_form
checkboxoptionalFor multiple-choice questions
custom_idoptional
email, name, question, textareaoptionalFor open questions (text answer)
group_chooseroptionalFor group-choice questions
propertiesoptionalThe Properties object
radio, selectoptionalFor single-choice questions
Sample Filled form event
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",  // generated server-side
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
	"recipients": "all",
	"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

Message event contains text message to other chat users.

FieldReq./Opt.Notes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default), agents
textrequiredMax. 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.
typerequiredmessage
custom_idoptional
postbackoptionalAppears in the message event only when triggered by a rich message.
postback.typeoptionalRequired only if postback.value is present.
postback.valueoptionalRequired only if postback.type is present.
propertiesoptionalThe properties object
Sample Message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "recipients": "all",
  "properties": {
    // "Properties" object
  }
}

Rich message

Rich message event contains rich message data structure. Read more in a document dedicated to Rich messages.

FieldReq./Opt.Notes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default), agents
template_idrequiredDescribes how the event should be presented in an app.
typerequiredrich_message
custom_idoptional
elementsoptionalMay contain 1 - 10 element objects.
elements.buttonsoptionalbuttons may contain 1 - 11 button objects.
elements.buttons.postback_idoptionalRequired only if elements.buttons is present. Describes the action sent via send_rich_message_postback. Multiple buttons (even from different elements) can contain the same postback_id. Calling send_rich_message_postback with this id will add a user to all those buttons at once.
elements.buttons.textoptionalRequired only if elements.buttons is present.
elements.buttons.typeoptionalRequired only if both elements.buttons and elements.buttons.value are present.
elements.buttons.user_idsoptionalRequired only if elements.buttons is present. Describes users that sent the postback with "toggled": true.
elements.buttons.valueoptionalRequired only if both elements.buttons and elements.buttons.type are present.
elements.buttons.webview_heightoptionalPossible values: compact, full, tall
elements.imageoptionalimage properties are optional: name, url, content_type, size, width, height.
elements.subtitleoptional
elements.titleoptional
propertiesoptionalThe properties object
Sample Rich message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "rich_message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "recipients": "all",
  "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://domain.com/asdsfdsf.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": []
        }
      ]
    },
    {
      "title": "Lorem ipsum dolor 2."
    }
  ]
}

Custom

Custom event is an event with customizable payload.

FieldReq./Opt.Note
recipientsrequiredPossible values: all (default), agents
typerequiredcustom
custom_idoptional-
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
propertiesoptional-
Sample Custom event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "custom",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c", // generated server-side
  "content": {
    "custom": {
      "nested": "json"
    }
  },
  "recipients": "all",
  "properties": {
    // "Properties" object
  }
}

System message

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

FieldReq./Opt.Notes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default for system events), agents (for events sent via send_event)
typerequiredsystem_message
system_message_typerequired
custom_idoptional
Sample System message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "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 as a Customer:

agent_added

ContentGenerated when
%initiator% added %agent% to the chatAgent was added to chat via the add_user_to_chat request and is not the first Agent in that chat.

agent_removed

ContentGenerated when
%initiator% removed %agent% from the chatAgent was removed from chat via the remove_user_from_chat request.

archived_customer_disconnected

ContentGenerated when
%customer% left the chatChat ended after Customer left the website.

chat_transferred

ContentGenerated when
%initiator% transferred the chat to %targets%Chat was transferred via the transfer_chat request.

customer_added

ContentGenerated when
%initiator% added %customer% to the chatCustomer was added to chat via the add_user_to_chat request.

customer_banned

ContentGenerated when
Chat archived because customer was banned by %agent% for %duration% day(s)Chat ended becaus Customer was banned via the ban_customer request.

customer_removed

ContentGenerated when
%initiator% removed %customer% from the chatCustomer was removed from chat via the remove_user_from_chat request.

manual_archived_agent

ContentGenerated when
%agent% archived the chatAgent closed chat via the close_thread request.

manual_archived_customer

ContentGenerated when
%customer% archived the chatCustomer closed chat via the close_thread request.

rating.chat_commented

ContentGenerated when
%customer% left the following comment: %comment%Chat was commented by Customer.

rating.chat_rated

ContentGenerated when
%customer% rated the chat as %score%Chat was rated by Customer.

rating.chat_rating_canceled

ContentGenerated when
%customer% canceled the chat ratingChat rating was cancelled by Customer.

routing.archived_deleted

ContentGenerated when
The chat was closed because %agent% account had been deletedChat was archived after Agent was removed from the license. No other Agent could be selected, and queues were disabled.

routing.archived_disconnected

ContentGenerated when
The chat was closed because %agent% had lost internet connectionChat was archived after Agent unexpectedly lost connection. No other Agent could be selected, and queues were disabled.

routing.archived_inactive

ContentGenerated when
Chat archived due to %duration% minutes of inactivityNo new messages were posted for an extended amount of time.

routing.archived_offline

ContentGenerated when
Chat archived due to no available agentsNo Agent could be selected after chat was placed in the queue.

routing.archived_other

ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

routing.archived_remotely_signed_out

ContentGenerated when
The chat was closed because %agent% had been remotely signed outChat was archived after an Agent was logged out. No other Agent could be selected and queues were disabled.

routing.archived_signed_out

ContentGenerated when
The chat was closed because %agent% had signed outChat was archived after Agent logged out. No other Agent could be selected, and queues were disabled.

routing.assigned_deleted

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% account had been deletedChat was assigned to a new Agent after the previous one was removed from the license.

routing.assigned_disconnected

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had lost internet connectionChat was assigned to a new Agent after the previous one unexpectedly lost connection.

routing.assigned_inactive

ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutesChat was assigned to a new Agent after the previous one failed to response in a timely manner.

routing.assigned_other

ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

routing.assigned_remotely_signed_out

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had been remotely signed outChat was assigned to a new Agent after the previous one was logged out.

routing.assigned_signed_out

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had signed outChat was assigned to a new Agent after the previous one logged out.

routing.unassigned_deleted

ContentGenerated when
Customer was queued because %agent% account has been deletedChat was queued after Agent was removed from the license.

routing.unassigned_disconnected

ContentGenerated when
Customer was queued because %agent% had lost internet connectionChat was queued after Agent unexpectedly lost connection.

routing.unassigned_other

ContentGenerated when
Chat is unassignedChat was queued after Agent was removed from chat for other reasons.

routing.unassigned_remotely_signed_out

ContentGenerated when
Customer was queued because %agent% had been remotely signed outChat was queued after Agent was logged out.

routing.unassigned_signed_out

ContentGenerated when
Customer was queued because %agent% had signed outChat was queued after Agent logged out.

system_archived

ContentGenerated when
Chat archivedLicense was moved to another lc_serv instance while there were still active chats.

transcript_requested

ContentGenerated when
%customer% requested the chat transcript to be sent to %email%Customer enables transcript.

Users

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

Customer

Sample Customer data structure
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "https://domain.com/avatars/1.jpg",
  "fields": {
    "custom field name": "custom field value"
  },
  "present": true,
  "events_seen_up_to": "2017-10-12T15:19:21.010200Z"
}
FieldReq./Opt.
avataroptional
fieldsoptional

Agent

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"
}

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
{
  "access": {
    "group_ids": [1, 2]
  }
}
FieldReq./Opt.Note
group_idsrequiredgroup 0 means that all agents can see it.

Chats

Sample Chat data structure
{
  "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.Note
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
{
  "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
}

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
{
  "properties": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure
{
  "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 endpoint
POSThttps://api.livechatinc.com/v3.1/customer/action/<action>
HeaderValueNotes
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.1You 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 parameterData typeNotes
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
      }'

Available methods

Run in Postman

Chats

Get Chats Summary

It returns summaries of the chats a Customer participated in.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_chats_summary
RTM API equivalentget_chats_summary
Webhook-
Request
ParameterRequiredTypeNotes
offsetNonumberDefault: 0, maximum: 100
limitNonumberDefault: 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
{
  "chats_summary": [
    {
      "id": "123",
      "order": 343544565,
      "last_thread_id": "xyz",
      "users": [
        // array of "User" objects
      ],
      "properties": {
        // "Properties" object
      },
      "access": {
        // "Access" object
      },
      "last_event_per_type": {
        // last event of each type in chat
        "message": {
          "thread_id": "K600PKZON8",
          "thread_order": 3,
          "event": {
            // "Event > Message" object
          }
        },
        "system_message": {
          "thread_id": "K600PKZON8",
          "thread_order": 3,
          "event": {
            // "Event > System message" object
          }
        }
        // ...
      }
    }
  ],
  "total_chats": 20
}

Get Chat Threads Summary

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_chat_threads_summary
RTM API equivalentget_chat_threads_summary
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstring
offsetNonumberDefault: 0
limitNonumberDefault: 25, maximum: 100
Response
ParameterNotes
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": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
      "order": 2,
      "total_events": 1
    },
    {
      "id": "b0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
      "order": 1,
      "total_events": 0
    }
  ],
  "total_threads": 4
}

Get Chat Threads

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_chat_threads
RTM API equivalentget_chat_threads
Webhook-
Request
ParameterRequiredData type
chat_idYesstring
thread_idsNoarray
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": ["a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5"]
      }'
Response
{
  "chat": {
    "id": "PJ0MRSHTDG",
    "order": 343544565,
    "users": [
      // array of "User" objects
    ],
    "properties": {
      // "Properties" object
    },
    "access": {
      // "Access" object
    },
    "threads": [
      // array of "Thread" objects
    ]
  }
}

Start Chat

Starts a chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/start_chat
RTM API equivalentstart_chat
Webhookincoming_chat_thread
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobjectInitial chat properties
chat.accessNoobjectChat access to set; default: all agents.
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial chat thread properties
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
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"
}

Activate Chat

Used to restart an archived chat.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/activate_chat
RTM API equivalentactivate_chat
Webhookincoming_chat_thread
Request
Request objectRequiredTypeNotes
chatYesobject
chat.idYesstringID of the chat that will be activated.
chat.accessNoobjectChat access to set; default: all agents.
chat.propertiesNoobjectInitial chat properties
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
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"
}

Close Thread

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

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/close_thread
RTM API equivalentclose_thread
Webhookincoming_event and thread_closed
Request
ParameterRequiredData type
chat_idYesstring
Response

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"
      }'

Events

Send Event

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/send_event
RTM API equivalentsend_event
Webhookincoming_event
Request
ParametersRequiredData typeNotes
chat_idYesstringId of the chat that you to send a message to.
eventYesobjectThe event object
attach_to_last_threadNoboolIf 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"
}

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/customer/action/upload_file
RTM API equivalent-
Webhookincoming_event *

*) incoming_event returns a URL that never expires.

Request
ParameterRequiredData typeNotes
fileYesbinaryMaximum 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.png
Response
{
  "url": "https://cdn.livechat-static.com/api/file/lc/att/8948324/45a3581b59a7295145c3825c86ec7ab3/image.png"
}

Send Rich Message Postback

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/send_rich_message_postback
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 or false
thread_idYesstring
Response

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
          }
      }'

Send Sneak Peek

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/send_sneak_peek
RTM API equivalentsend_sneak_peek
Webhook-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you to set a sneak peek to.
sneak_peek_textYesstringSneak peek text
Response

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"
          }
      }'

Properties

Update Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/update_chat_properties
RTM API equivalentupdate_chat_properties
Webhookchat_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you to set a property 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
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!"
              }
          }
      }'

Delete Chat Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/delete_chat_properties
Required scopes*chats.conversation--all:write chats.conversation--my:write
RTM API equivalentdelete_chat_properties
Webhookchat_properties_deleted

*)

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats the requester belongs to
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
propertiesYesobjectChat properties to delete.
Response

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"
              ]
          }
      }'

Update Chat Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/update_chat_thread_properties
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.
Response

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!"
              }
          }
      }'

Delete Chat Thread Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/delete_chat_thread_properties
Required scopes*chats.conversation--all:write chats.conversation--my:write
RTM API equivalentdelete_chat_thread_properties
Webhookchat_thread_properties_deleted

*)

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats the requester belongs to
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.
propertiesYesobjectChat thread properties to delete.
Response

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"
              ]
          }
      }'

Update Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/update_event_properties
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
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!"
              }
          }
      }'

Delete Event Properties

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/delete_event_properties
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. You should stick to the general properties format and include namespace, property name and value.
Response

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"
            ]
        }
    }'

Customers

Update Customer

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/update_customer
RTM API equivalentupdate_customer
Webhook-
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringThe URL of the Customer's avatar
fieldsNoobjectkey: value format

At least one optional parameter needs to be included in the request.

Response

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"
      }'

Set Customer Fields

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/set_customer_fields
RTM API equivalentset_customer_fields
Webhookcustomer_updated
Request
ParameterRequiredData typeNotes
fieldsYesobjectkey:value format

Users Agent and referrer are updated by default using the browser’s headers.

Response

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"
      		}
      }'

Status

Get Groups Status

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_groups_status
RTM API equivalentget_groups_status
Webhook-
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, you will get statuses of all the groups.
groupsNoarrayA table of groups' IDs

One of the optional parameters needs to be included in the request.

Response

No response payload (200 OK).

Response
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,2,3 are group ids, online/offline/online_for_queue are statuses of the groups

    1: "online",
    2: "offline",
    3: "online_for_queue"
  }
}

Other

Check Goals

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.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/check_goals
RTM API equivalent-
Webhook-
Request
ParameterRequiredData typeNotes
customer_fieldsYesobjectkey:value format
group_idYesnumber
page_urlYesstring
Response

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
}'

Get Form

Returns an empty ticket form of a prechat or postchat survey.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_form
RTM API equivalentget_form
Webhook-
Request
ParameterRequiredData typeNotes
group_idYesnumberId of the group from which you want the form.
typeYesstringForm type; possible values: prechat or postchat
Response
ParameterNotes
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
}

Get Predicted Agent

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.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_predicted_agent
RTM API equivalentget_predicted_agent
Webhook-
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
{
  "agent": {
    "id": "agent1@example.com",
    "name": "Name",
    "avatar": "https://example.avatar/example.com",
    "is_bot": false,
    "job_title": "support hero",
    "type": "agent"
  }
}

Get URL Details

It returns the info on a given URL.

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/get_url_details
RTM API equivalentget_url_details
Webhook-
Request
ParameterRequiredData typeNotes
urlYesstringValid 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"
}

Mark Events As Seen

Specifics
Method URLhttps://api.livechatinc.com/v3.1/customer/action/mark_events_as_seen
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
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"
      }'

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
{
  "error": {
    "type": "misdirected_request",
    "message": "Wrong region",
    "data": {
      // optional
      "region": "dal"
    }
  }
}
Possible errors
TypeDefault MessageNotes
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorAgent 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_request*Wrong regionClient's request should be performed to another region.
validationWrong format of request
request_timeoutRequest timed outTimeout threshold is 15 seconds.
unsupported_versionUnsupported versionUnsupported protocol version.
wrong_product_versionWrong product versionLicense is not LiveChat 3 (probably still LiveChat 2).

*) misdirected_request error returns also correct region in optional data object. With this information client is able to figure out where he should be connected.

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!