platform.text.com
Open in
urlscan Pro
23.48.107.56
Public Scan
Submitted URL: http://api.livechatinc.com/
Effective URL: https://platform.text.com/docs/management/configuration-api/v2.0/
Submission: On October 02 via manual from AU — Scanned from AU
Effective URL: https://platform.text.com/docs/management/configuration-api/v2.0/
Submission: On October 02 via manual from AU — Scanned from AU
Form analysis 0 forms found in the DOM
Text Content
text|
Platform Docs
Platform
APIs & SDKs
Resources
SearchK
SearchK
Configuration API
Home
Management Overview
Configuration API
Webhooks
Changelog
CONFIGURATION API
WAS THIS PAGE HELPFUL?
INTRODUCTION
Welcome to the LiveChat API documentation!
Our API provides a set of flexible tools which you can use to create new
outstanding projects. We smile a bit more each time we see skilled developers
unleash their creativity!
Please note that this documentation refers to the API version 2.0. This is the
deprecated version. We encourage you to migrate to the latest stable version.
Read more about versioning...
BASIC API USAGE
All LiveChat API requests start with https://api.livechatinc.com/.
Please note that all LiveChat API requests must use `HTTPS` protocol.
The next segment of the URL path depends on the type of your request. For
example, use: https://api.livechatinc.com/agents to get or modify the agents
data.
All requests must have `X-API-VERSION` header set to the number of the version
that you'd like to use. The most recent version is 2.
DATA CENTERS
LiveChat system operates in two data centers: dal and fra. The default data
center is dal.
All the LiveChat OAuth 2.1 access tokens have a prefix: dal: or fra:. This
prefix indicates the data center they belong to. If you need to specify the data
center while making an API call, simply add the X-Region: <token_prefix>
optional header.
For example: if the user token starts with fra, you should add X-Region: fra
header. If the token starts with dal you don't have to specify the header.
If you get the Misdirected request error, use the prefix returned in the error
as the value of X-Region.
AUTHENTICATION
There are two common authorization methods supported: OAuth 2.1 and Personal
Access Token (PAT).
OAUTH 2.1
Example REST API call using OAuth 2.1 access_token:
curl "https://api.livechatinc.com/agents" \
-H "Authorization: Bearer <your_access_token>" \
-H "X-API-Version: 2"
OAuth 2.1 authentication is the recommended way of authenticating to LiveChat
API.
It is the most secure way of making API calls. With this flow, you will get
access only to some parts of LiveChat account, such as reading agents list.
To start using OAuth 2.1, please read a dedicated Authorization guide.
PERSONAL ACCESS TOKEN
Personal Access Tokens (PATs) are generated per Agent. They use Basic
authentication scheme. You can create a PAT from Developer Console. For more
guidelines on creating PATs, check out this tutorial.
Example REST API call using a PAT:
curl "https://api.livechatinc.com/groups" \
-H "Authorization: Basic <email>:<PAT>" \
-H "X-API-Version: 2"
💡 When sending authorization credentials in a header, the email:PAT string has
to be base64-encoded. Alternatively, enter your credentials in the Authorization
tab in Postman, which will automatically encode them for you (see the image
below).
DATA FORMAT
The LiveChat API returns the data in the JSON format. Check out the following
example.
Sample agents list returned in the JSON format
[
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
...
]
JSONP
Sample JSONP request
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb "https://api.livechatinc.com/agents?callback=example"
All requests made with HTTP GET are JSONP-enabled. To use JSONP, append
callback= and the name of your callback function to the request.
Sample JSONP response
[
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
...
]
ERROR HANDLING
The errors are returned using the standard HTTP error code syntax. In general,
the codes in the 2xx range indicate success, the codes in the 4xx range indicate
an error (incorrect or missing parameters, not authenticated etc.), and the
codes in the 5xx range indicate an error with the LiveChat servers. Any
additional info is included in the body of the return call, JSON-formatted.
HTTP STATUS CODES SUMMARY
* 400 – The request is incorrect, please make sure that the passed arguments
are matching the format in the method's documentation.
* 401 – Unauthorized. You attempt to authenticate with an invalid username or
access token.
* 404 – Not Found. You attempt to request a resource which doesn't exist.
* 500 – Internal Server Error. Something unexpected happened on our end. Please
try again or contact our support.
CROSS-DOMAIN
All cross-domain API requests made by a web browser are denied for security
reasons. It means that the browser-based requests are not allowed from 3rd party
domains (including localhost).
LIVECHAT API LIBRARIES
You can call the LiveChat API using librariers written in backend languages. To
authorize your requests while using those libraries, use a Personal Access
Token.
* PHP library for LiveChat API, hosted on Github.
* node.js library for LiveChat API, hosted on Github.
* Ruby library for LiveChat API, hosted on Github.
* C# library for LiveChat API, hosted on Github.
EXTERNAL LIVECHAT API LIBRARIES
* R library for LiveChat API, hosted on Github.
Did you write your own library and want it listed here? Let us know!
AGENTS (DEPRECATED)
Please note this API is deprecated. We highly recommend switching to the new
Management APIs.
Use this API to manage your Agents and to get information about their
activities.
MethodsPathGET, POST/agentsGET, PUT, DELETE/agents/<LOGIN>
LIST ALL AGENTS (DEPRECATED)
We highly recommend switching to the new List Agents method.
Returns all LiveChat agents list.
REQUIRED SCOPES
* agents--all:ro
Or, agents_read if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
OPTIONAL PARAMETERS
ParameterDescriptionstatusreturns the agents with one of the following statuses:
accepting chats, not accepting chats or offline
ADDITIONAL INFO
status can be: accepting chats, not accepting chats or offline.
permission can take the following values: owner, administrator, normal.
GET /agents
Copied!
curl "https://api.livechatinc.com/agents" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \
-H X-API-Version:2
Response
Copied!
[
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
...
]
GET A SINGLE AGENT DETAILS (DEPRECATED)
We highly recommend switching to the new Get Agent method.
Returns complete details of the agent for the given LOGIN.
REQUIRED SCOPES
* agents--all:ro
Or, agents_read if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
PARAMETERS
ParameterDescriptionloginthe agent's e-mail addressnamethe agent's
namelogin_statuspossible values: accepting chats, not accepting chats; defines
the default status for an agent right after the loginpermissionpossible values:
owner, administrator, normaldaily_summarywhether or not the agent receives a
daily summaryjob_titledefaults to: Support Agentavatarpath to the image on
Amazon s3notificationswhether or not the specific notification is
enabledmax_chats_countlimit of the concurrent chatsgroups[]list of groups the
agent is a member ofstatuspossible values: accepting chats, not accepting chats,
offline; current status of an agentlast_logouttimestamp of the agent's last
logout
GET /agents/<LOGIN>
Copied!
curl "https://api.livechatinc.com/agents/john.doe@mycompany.com" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"login": "john.doe@mycompany.com",
"name": "John Doe",
"login_status": "accepting chats",
"permission": "owner",
"daily_summary": 1,
"job_title": "Support Agent",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"notifications": {
"new_visitor": 1,
"returning_visitor": 1,
"queued_visitor": 1,
"visitor_is_typing": 0,
"new_goal": 1
},
"max_chats_count": 6,
"groups": [
{
"id": 1,
"name": "Sales"
},
{
"id": 2,
"name": "Technical Support"
}
],
"status": "accepting chats",
"last_logout": 1358427204
}
CREATE A NEW AGENT (DEPRECATED)
We highly recommend switching to the new Create Agent method.
Creates a new agent in your license.
REQUIRED SCOPES
* accounts--all:r
* agents--all:rw (only for the pay per seat pricing model)
Or, agents_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
REQUIRED PARAMETERS
ParameterDescriptionloginmust be a correct e-mail addressnamestring
OPTIONAL PARAMETERS
ParameterDescriptionjob_titledefaults to: Support Agentlogin_statuspossible
values: accepting chats, not accepting chats; defines the default status for an
agent right after the loginpasswordthe minimum length is 5 (if not provided, an
email with the activation link will be sent)permissionadministrator, normal
(default)groups[]list of group IDsnotificationsobject (required keys:
new_visitor, incoming_chat, returning_visitor, queued_visitor,
visitor_is_typing, new_goal, accepted values: 0 or 1)daily_summary0 or 1
(default)max_chats_countdefaults to 6
POST /agents
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/agents" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"login":"jenny.doe@mycompany.com",
"name":"Jenny Doe",
"permission":"administrator",
"groups":[1,2]
}'
Response
Copied!
{
"login": "jenny.doe@mycompany.com",
"name": "Jenny Doe",
"login_status": "accepting chats",
"permission": "administrator",
"daily_summary": 1,
"job_title": "Support Agent",
"avatar": "livechat.s3.amazonaws.com/default/avatars/45bcb5f592dbf5aac8f88dcfd6bc937c.png",
"notifications": {
"new_visitor": 1,
"returning_visitor": 1,
"queued_visitor": 1,
"visitor_is_typing": 0,
"new_goal": 1
},
"max_chats_count": 6,
"groups": [
{
"id": 1,
"name": "Sales"
},
{
"id": 2,
"name": "Technical Support"
}
],
"status": "offline",
"last_logout": 0
}
UPDATE AN AGENT (DEPRECATED)
We highly recommend switching to the new Update Agent method.
Updates the specified agent by setting the values of the parameters passed. Any
parameters not provided will be left unchanged.
REQUIRED SCOPES
* agents--my:rw
Or, agents_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
OPTIONAL PARAMETERS
ParameterDescriptionjob_titlenamelogin_statuspossible values: accepting chats,
not accepting chats; defines the default status for agent right after
loginpasswordthe password you want to changecurrent_passwordwhen changing the
password for yourself or for another agent, you need to provide your current
passwordpermissionadministrator, normal (default)statusaccepting chats, not
accepting chats, offlinegroups[]list of group IDsnotificationsobject (allowed
keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, allowed
values: 0 or 1)daily_summary0 or 1max_chats_countwork_scheduleravailable only
for enterprise plan
The properties which an agent can edit in their own profile, without being an
administrator:
* password
* name
* job_title
* daily_summary
* notifications
* login_status
* status
PUT /agents/<LOGIN>
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-X PUT \
-d '{
"status":"not accepting chats",
"max_chats_count":2
}'
Response
Copied!
{
"login": "jenny.doe@mycompany.com",
"name": "Jenny Doe",
"login_status": "not accepting chats",
"permission": "administrator",
"daily_summary": 1,
"job_title": "Support Agent",
"avatar": "livechat.s3.amazonaws.com/default/avatars/45bcb5f592dbf5aac8f88dcfd6bc937c.png",
"notifications": {
"new_visitor": 1,
"returning_visitor": 1,
"queued_visitor": 1,
"visitor_is_typing": 0,
"new_goal": 1
},
"max_chats_count": 2,
"work_scheduler":{
"sunday":{
"enabled":0,
"start":"11:00",
"end":"17:00"
},
"monday":{
"enabled":1,
"start":"09:00",
"end":"17:00"
},
...
"saturday":{
"enabled":0,
"start":"09:00",
"end":"17:00"
}
},
"groups": [
{
"id": 1,
"name": "Sales"
},
{
"id": 2,
"name": "Technical Support"
}
],
"status": "not accepting chats",
"last_logout": 0
}
REMOVE AN AGENT (DEPRECATED)
We highly recommend switching to the new Delete Agent method.
Removes an agent. Archived chats will not be removed, but all statistics will be
lost. The agent will be notified by e-mail that the account has been deleted.
REQUIRED SCOPES
* agents--all:rw
Or, agents_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
DELETE /agents/<LOGIN>
Copied!
curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"result": "jenny.doe@mycompany.com removed successfully"
}
ARCHIVES (DEPRECATED)
Please note this API is deprecated. We highly recommend switching to the new
Messaging APIs.
This API allows you to look up the past chats and after-hours messages. It also
allows you to send chat transcripts via email.
AVAILABLE PATHS
MethodsPathGET/chatsGET/chats/<CHAT_ID>POST/chats/<CHAT_ID>/send_transcriptPUT/chats/<CHAT_ID>/tags
GET LIST OF CHATS (DEPRECATED)
We highly recommend switching to the new List Chats method.
Returns all ended chats.
REQUIRED SCOPES
* archives_read
OPTIONAL PARAMETERS
ParameterDescriptiondate_fromYYYY-MM-DD Defaults to the beginning of
timedate_toYYYY-MM-DD Defaults to todaytimezonetimezone in the TZ format (e.g.
America/Phoenix)pagepage number, defaults to 1visitor_idreturn chats with
specified visitor_idqueryreturn chats containing the queryagentreturn chats for
given agent logingroupreturn chats for given group idgoalreturn chats for given
goal idhas_goal1/0. If 1 is passed, returns chats having any goalsalereturn
chats for given sales tracker idhas_sale1/0. If 1 is passed, returns chats
having any tracked salequeued1/0. If 1 is passed, returns chats started from
queueratefilter chats considering its rating status. Available values: rated,
not_rated, rated_good, rated_badinclude_pending1/0. Whether to include chats
that haven't yet ended. Pending chats can be recognized by pending: true
attribute. They may appear with some delay because of caching reasonstag[]filter
chats by a specified tagtagged1/0. If 1 is passed, chats with any tag are
returned. If 0 is passed, only chats without a tag are returnedcomment1/0. If 1
is passed, chats with rating comments are returnedcityfilters by city, values
should be entered and are returned in the local languageregionfilters by region.
This could be a state, voivodeship, canton, county etc. Values should be entered
and are returned in the local languagecountryfilters by country name. All values
are in English
ADDITIONAL INFO
ParameterDescriptiongoalparameter will appear only if a goal has been reached or
there was tracked sale for a particular chatreferrerparameter will appear only
if referrer url existscustom_variablesparameter will be available only if the
custom variables are defined in the tracking codeintegration_variablesparameter
will appear only if a visitor logs in with Facebookqueueparameter will appear
only if chat started from queueengagement– possible values: auto_invite (chat
from automatic invitation), manual_invite (chat from manual invitation),
immediate_start (visitor started chats themselves)durationis counted in
secondstotaltells you the total number of chatspagestells you the total number
of pagescity, region, countrygeolocation filters have been working for chats
since May 11, 2015
The results are divided into pages, each containing 25 chats. To access next
pages of the results, use ?page=<PAGE> parameter. Please note that first page's
number is 1, not 0.
Note that the results are limited to the latest 25000 records on your LiveChat
license, which gives you exactly 1000 pages with 25 chats per page. If you have
more than 25000 chats on your license and you want to get them all, you will
have to call our API several times.
In the first call, use the data range that covers the first 25000 chats. When
making other calls, use the data range that includes the rest of your
conversations.
GET /chats
Copied!
curl "https://api.livechatinc.com/chats?\
date_from=2013-01-23&\
has_goal=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"chats": [
{
"type": "chat",
"id": "MH022RD0K5",
"visitor": {
"id": "S1355415390.49b8940793",
"name": "Mary Brown",
"ip": "85.10.5.156",
"city": "Central District",
"country": "Hong Kong",
"country_code": "HK",
"timezone": "Asia/Hong_Kong",
"region": "",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
},
"agents": [
{
"display_name": "John Doe",
"email": "john.doe@mycompany.com"
}
],
"supervisors": [
{
"display_name": "Jane Doe",
"email": "jane.doe@mycompany.com"
}
],
"rate": "not_rated",
"duration": 1456,
"chat_start_url": "https://livechatinc.com",
"referrer": "https://example.com",
"group": [0],
"started": "Wed, 01/23/13 11:40:53 am",
"prechat_survey": [
{
"key": "Name:",
"value": "",
"id": "13589376348060238"
},
{
"key": "E-mail:",
"value": "",
"id": "135893763480606511"
}
],
"postchat_survey": [
{
"key": "How would you rate the quality of support?",
"value": "Good",
"id": "137164167769201638"
}
],
"custom_variables": [
{
"key": "customer_login",
"value": "mary_brown"
}
],
"integration_variables": [
{
"key": "facebook.id",
"value": "123456789"
},
{
"key": "facebook.email",
"value": "mary.brown@email.com"
}
// ...
],
"goals": [
{
"id": 71,
"name": "sales_tracker_name",
"type": "sales_tracker",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"order": {
"id": "ABC",
"description": "product one",
"price": "199",
"currency": "CZK"
}
},
{
"id": 72,
"name": "goal_name",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"order": {
"id": "",
"description": "",
"price": "0",
"currency": ""
}
}
],
"queue": {
"duration": 20
},
"tags": ["sales", "support", "feedback"],
"timezone": "Europe/Berlin",
"messages": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com"
}
// ...
],
"events": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com",
"type": "message"
},
{
"text": "Mary Brown uploaded the attachment.",
"date": "Wed, 01/23/13 11:41:02 am",
"timestamp": 1358937662,
"type": "attachment",
"user_type": "visitor",
"files": ["https://static.livechatinc.com/.../hello.JPG"],
"author_name": "Mary Brown"
},
{
"author_name": "John Doe",
"text": "Thanks, fine :)",
"date": "Wed, 01/23/13 11:41:05 am",
"timestamp": 1358937665,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com",
"type": "message"
},
{
"author_name": "Jane Doe",
"text": "Message from supervisor.",
"date": "Wed, 01/23/13 11:57:13 am",
"timestamp": 1358938633,
"user_type": "supervisor",
"agent_id": "jane.doe@mycompany.com",
"type": "message"
},
{
"text": "Mary Brown closed the chat.",
"date": "Wed, 01/23/13 11:57:14 am",
"timestamp": 1358937663,
"type": "event",
"event_type": "closed",
"user_type": "visitor"
}
],
"engagement": immediate_start,
"started_timestamp": 1358937653,
"ended_timestamp": 1358939109,
"ended": "Wed, 01/23/13 12:05:09 pm"
},
{
"...": "..."
}
],
"total": 2,
"pages": 1
}
GET SINGLE CHAT (DEPRECATED)
We highly recommend switching to the new Get Chat method.
Returns a single chat item for the given CHAT_ID.
REQUIRED SCOPES
* archives_read
GET chats/<CHAT_ID>
Copied!
curl "https://api.livechatinc.com/chats/MH022RD0K5" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"type": "chat",
"id": "MH022RD0K5",
"visitor": {
"id": "S1355415390.49b8940793",
"name": "Mary Brown",
"ip": "85.10.5.156",
"city": "Central District",
"country": "Hong Kong",
"country_code": "HK",
"timezone": "Asia/Hong_Kong",
"region": "",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
},
"agents": [
{
"display_name": "John Doe",
"email": "john.doe@mycompany.com"
}
],
"supervisors": [
{
"display_name": "Jane Doe",
"email": "jane.doe@mycompany.com"
}
],
"rate": "not_rated",
"duration": 1456,
"chat_start_url": "https://livechatinc.com",
"referrer": "https://example.com",
"group": [0],
"started": "Wed, 01/23/13 11:40:53 am",
"prechat_survey": [
{
"key": "Name:",
"value": "",
"id": "13589376348060238"
},
{
"key": "E-mail:",
"value": "",
"id": "135893763480606511"
}
],
"postchat_survey": [
{
"key": "How would you rate the quality of support?",
"value": "Good",
"id": "137164167769201638"
}
],
"custom_variables": [
{
"key": "customer_login",
"value": "mary_brown"
}
],
"integration_variables": [
{
"key": "facebook.id",
"value": "123456789"
},
{
"key": "facebook.email",
"value": "mary.brown@email.com"
}
// ...
],
"goals": [
{
"id": 71,
"name": "sales_tracker_name",
"type": "sales_tracker",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"order": {
"id": "ABC",
"description": "product one",
"price": "199",
"currency": "CZK"
}
},
{
"id": 72,
"name": "goal_name",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"order": {
"id": "",
"description": "",
"price": "0",
"currency": ""
}
}
],
"queue": {
"duration": 20
},
"tags": ["sales", "support", "feedback"],
"timezone": "Europe/Berlin",
"messages": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com"
}
// ...
],
"events": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com",
"type": "message"
},
{
"text": "Mary Brown uploaded the attachment.",
"date": "Wed, 01/23/13 11:41:02 am",
"timestamp": 1358937662,
"type": "attachment",
"user_type": "visitor",
"files": ["https://static.livechatinc.com/.../hello.JPG"],
"author_name": "Mary Brown"
},
{
"author_name": "John Doe",
"text": "Thanks, fine :)",
"date": "Wed, 01/23/13 11:41:05 am",
"timestamp": 1358937665,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com",
"type": "message"
},
{
"author_name": "Jane Doe",
"text": "Message from supervisor.",
"date": "Wed, 01/23/13 11:57:13 am",
"timestamp": 1358938633,
"user_type": "supervisor",
"agent_id": "jane.doe@mycompany.com",
"type": "message"
},
{
"text": "Mary Brown closed the chat.",
"date": "Wed, 01/23/13 11:57:14 am",
"timestamp": 1358937663,
"type": "event",
"event_type": "closed",
"user_type": "visitor"
}
],
"engagement": immediate_start,
"started_timestamp": 1358937653,
"ended_timestamp": 1358939109,
"ended": "Wed, 01/23/13 12:05:09 pm"
}
UPDATE CHAT TAGS (DEPRECATED)
We highly recommend switching to the new Tag Thread and Untag Thread methods.
This method updates the tags assigned to a chat.
REQUIRED SCOPES
* archives_write
REQUIRED PARAMETERS
ParameterDescriptiontagarray of used tags
PUT /chats/<CHAT_ID>/tags
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/chats/MH022RD0K5/tags" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-X PUT \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"tag[]":"sales",
"tag[]":"support",
"tag[]":"feedback"
}'
Response
Copied!
{
"chats": [
{
"type": "chat",
"id": "MH022RD0K5",
"visitor": {
"id": "S1355415390.49b8940793",
"name": "Mary Brown",
"ip": "85.10.5.156",
"city": "Central District",
"country": "Hong Kong",
"country_code": "HK",
"timezone": "Asia/Hong_Kong",
"region": ""
},
"agents": [
{
"display_name": "John Doe",
"email": "john.doe@mycompany.com"
}
],
"supervisors": [
{
"display_name": "Jane Doe",
"email": "jane.doe@mycompany.com"
}
],
"rate": "not_rated",
"duration": 1456,
"chat_start_url": "https://livechatinc.com",
"referrer": "https://example.com",
"group": [0],
"started": "Wed, 01/23/13 11:40:53 am",
"prechat_survey": [
{
"key": "Name:",
"value": "",
"id": "13589376348060238"
},
{
"key": "E-mail:",
"value": "",
"id": "135893763480606511"
}
],
"postchat_survey": [
{
"key": "How would you rate the quality of support?",
"value": "Good",
"id": "137164167769201638"
}
],
"custom_variables": [
{
"key": "customer_login",
"value": "mary_brown"
}
],
"integration_variables": [
{
"key": "facebook.id",
"value": "123456789"
},
{
"...": "..."
}
],
"goals": [
{
"id": 71,
"name": "goal_name",
"order": {
"id": "ABC",
"description": "product one",
"price": "199",
"currency": "CZK"
}
},
{
"id": 72,
"name": "goal_name",
"order": {}
}
],
"queue": {
"duration": 20
},
"tags": ["tag1", "tag2", "tag3"],
"timezone": "Europe/Berlin",
"messages": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com"
},
{
"...": "..."
}
],
"events": [
{
"author_name": "John Doe",
"text": "Hello",
"date": "Wed, 01/23/13 11:40:53 am",
"timestamp": 1358937653,
"user_type": "agent",
"agent_id": "john.doe@mycompany.com",
"type": "message"
},
{
"...": "..."
}
],
"engagement": immediate_start,
"started_timestamp": 1358937653,
"ended_timestamp": 1358939109,
"ended": "Wed, 01/23/13 12:05:09 pm"
},
{
"...": "..."
}
],
"total": 2,
"pages": 1
}
SEND CHAT TRANSCRIPT TO E-MAIL
REQUIRED SCOPES
* archives_read
REQUIRED PARAMETERS
ParameterDescriptiontoreceiver's email address.
POST /chats/<THREAD_ID>/send_transcript
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/chats/MH022RD0K5/send_transcript" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"to":"john.doe@mycompany.com"
}'
Response
Copied!
{
"result": "E-mail has been sent to john.doe@mycompany.com."
}
CANNED RESPONSES
Use this method to get a full list of your Canned responses and to modify them.
AVAILABLE PATHS
MethodsPathGET, POST/canned_responsesGET, PUT,
POST/canned_responses/<CANNED_RESPONSE_ID>
LIST ALL CANNED RESPONSES
Returns the list of all currently set canned responses.
REQUIRED SCOPES
* canned_responses_read
OPTIONAL PARAMETERS
ParameterDescriptiongroupdefaults to 0
ADDITIONAL INFO
* modification_date, modification_by - appear in the response if the canned
response has been modified.
GET /canned_responses
Copied!
curl "https://api.livechatinc.com/canned_responses?group=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
[
{
"id": 3151,
"group": 1,
"text": "Can I help you with anything else?",
"creation_date": 1358257181,
"created_by": "john.doe@mycompany.com",
"tags": ["help", "else"]
},
{
"id": 3161,
"group": 1,
"text": "What product are you interested in?",
"creation_date": 1358257229,
"created_by": "john.doe@mycompany.com",
"modification_date": 1358864338,
"modified_by": "jenny.doe@mycompany.com",
"tags": ["product", "interest"]
},
{
"...": "..."
}
]
GET A SINGLE CANNED RESPONSE
CANNED_RESPONSE_ID is obtained from the list of all canned responses.
REQUIRED SCOPES
* canned_responses_read
PARAMETERS
ParameterDescriptionidid of the canned responsegroupid of the group that canned
response is assigned totextcanned response textcreation_datecreation date
timestampcreated_bylogin of the canned response's authortagsan array of canned
response's tags
GET /canned_responses/<CANNED_RESPONSE_ID>
Copied!
curl "https://api.livechatinc.com/canned_responses/3151" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"id": 3151,
"group": 1,
"text": "Can I help you with anything else?",
"creation_date": 1358257181,
"created_by": "john.doe@mycompany.com",
"tags": ["help", "else"]
}
CREATE A NEW CANNED RESPONSE
Creates a new canned response.
REQUIRED SCOPES
* canned_responses_write
REQUIRED PARAMETERS
ParameterDescriptiontextresponse texttagsarray of strings (tags)
OPTIONAL PARAMETERS
ParameterDescriptiongroupdefaults to 0
POST /canned_responses
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/canned_responses" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"text":"Have a great day, goodbye.",
"tags": ["bye", "cu"]
}'
Response
Copied!
{
"id": 3181,
"group": 0,
"text": "Have a great day, goodbye.",
"creation_date": 1358866421,
"created_by": "john.doe@mycompany.com",
"tags": ["cu", "bye"]
}
UPDATE A CANNED RESPONSE
Updates the specified canned response by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
REQUIRED SCOPES
* canned_responses_write
OPTIONAL PARAMETERS
ParameterDescriptiontextresponse texttagsarray of strings (tags)
PUT /canned_responses/<CANNED_RESPONSE_ID>
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/canned_responses/3181" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X PUT -d "tags[]=bye"
Response
Copied!
{
"id": 3181,
"group": 0,
"text": "Have a great day, goodbye.",
"creation_date": 1358866421,
"created_by": "john.doe@mycompany.com",
"modification_date": 1358866813,
"modified_by": "john.doe@mycompany.com",
"tags": ["bye"]
}
REMOVE A CANNED RESPONSE
Removes a canned response with the given CANNED_RESPONSE_ID.
REQUIRED SCOPES
* canned_responses_write
DELETE /canned_responses/<CANNED_RESPONSE_ID>
Copied!
curl "https://api.livechatinc.com/canned_responses/3181" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"result": "Canned response removed successfully"
}
GOALS
This method allows you to get information about your Goals and to modify them.
AVAILABLE PATHS
MethodsPathGET, POST/goalsGET, PUT,
DELETE/goals/<GOAL_ID>POST/goals/<GOAL_ID>/mark_as_successful
LIST ALL GOALS
Returns all currently set goals. The active parameter indicates whether a goal
is enabled or not.
REQUIRED SCOPES
* goals_read
OPTIONAL PARAMETERS
ParameterDescriptiontypetype of the goal: custom_variable, url, api or
sales_tracker
GET /goals
Copied!
curl "https://api.livechatinc.com/goals" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
[
{
"id": 1041,
"name": "purchase",
"active": 1,
"type": "url"
},
{
"id": 1181,
"name": "nike shoes variable",
"active": 1,
"type": "custom_variable"
}
]
GET A SINGLE GOAL DETAILS
Returns the goal details for the given GOAL_ID.
REQUIRED SCOPES
* goals_read
PARAMETERS
ParameterDescriptionidid of the goalnamegoal nameactivewhether or not the goal
is enabledtypetype of the goal
ADDITIONAL INFO
The type attribute can take the following values:
* custom_variable – with two additional parameters: custom_variable_name,
custom_variable_value.
* url – with two additional parameters: url and match_type with possible
values: substring (default), exact.
* api – with no additional parameters.
* sales_tracker – with seven additional parameters: sales_tracker_id,
value_type, value, currency, time_range, order_field_name and
value_field_name
GET /goals/<GOAL_ID
Copied!
curl "https://api.livechatinc.com/goals/1181" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"id": 1181,
"name": "nike shoes variable",
"active": 1,
"type": "custom_variable",
"custom_variable_name": "nike_shoes",
"custom_variable_value": "true"
}
MARK A GOAL AS SUCCESSFUL
The GOAL_ID is obtained from the goals list.
REQUIRED SCOPES
* goals_write
REQUIRED PARAMETERS
ParameterDescriptionvisitor_idobtained using the JavaScript API:
LC_API.get_visitor_id()
Optionally you can store additional information about the goal. They can be only
retrieved using the API.
OPTIONAL PARAMETERS
ParameterExampleorder_idAP723HVCA721order_descriptionNike
shoesorder_price199.00, only the period is allowed as a separation
characterorder_currencyUSD
POST /goals/<GOAL_ID>/mark_as_successful
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/goals/1181/mark_as_successful" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"visitor_id":"S1281361958.2238ee3bd3",
}'
Response
Copied!
{
"result": "goal marked as successful"
}
ADD A NEW GOAL
Creates a new goal.
REQUIRED SCOPES
* goals_write
REQUIRED PARAMETERS
ParameterDescriptionnamename of the goaltypetype of the goal
ADDITIONAL INFO
The type can take the following values:
* custom_variable – with two additional parameters: custom_variable_name,
custom_variable_value. Both are required.
* url – with two additional parameters: url (required) and match_type
(optional) with possible values: substring (default), exact.
* api – with no additional parameters.
* sales_tracker – with optional parameters: value_type (possible values: set,
not_set, dynamic), value, currency, time_range, order_field_name,
value_field_name and sales_tracker_id
The active parameter indicates whether the goal is active or not.
POST /goals
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/goals" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"new goal",
"type":"url",
"url":"http://www.mystore.com/checkout/thank_you",
"match_type":"exact"
}'
Response
Copied!
{
"id": 2231,
"name": "new goal",
"active": 1,
"type": "url",
"match_type": "exact",
"url": "http://www.mystore.com/checkout/thank_you"
}
UPDATE A GOAL
Updates the specified goal by setting the values of the parameters passed. Any
parameters not provided will be left unchanged.
The GOAL_ID is obtained from the goals list.
REQUIRED SCOPES
* goals_write
OPTIONAL PARAMETERS
ParameterDescriptionnamename of the goaltypetype of the goalactiveactive state
of the goal
ADDITIONAL INFO
The type can take the following values:
* custom_variable – with two additional parameters: custom_variable_name,
custom_variable_value. Both are required.
* url – with two additional parameters: url (required) and match_type
(optional) with possible values: substring (default), exact.
* api – with no additional parameters.
* sales_tracker – with optional parameters: order_field_name, value_field_name
and sales_tracker_id
The active parameter indicates whether the goal is active or not.
PUT /goals/<GOAL_ID>
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/goals/2231" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"new goal paused",
"active":0
}'
Response
Copied!
{
"id": 2231,
"name": "new goal paused",
"active": 0,
"type": "url",
"match_type": "exact",
"url": "http://www.mystore.com/checkout/thank_you"
}
REMOVE A GOAL
Removes a goal with the given GOAL_ID.
REQUIRED SCOPES
* goals_write
DELETE /goals/<GOAL_ID>
Copied!
curl "https://api.livechatinc.com/goals/2231" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"result": "goal removed successfully"
}
GREETINGS
You can use this method to create new and modify the existing Greetings. It can
be also used to look up Greetings data.
AVAILABLE PATHS
MethodsPathGET, POST/greetingsGET, POST, DELETE/greetings/<GREETING_ID>
LIST ALL GREETINGS
Returns the list of all greetings.
REQUIRED SCOPES
* greetings_read
OPTIONAL PARAMETERS
ParameterDescriptiongroupGroup number can be specified to get greetings from a
given group. If not specified, all greetings will be returned
GET /greetings
Copied!
curl "https://api.livechatinc.com/greetings\
?group=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
[
{
"id": 2291,
"active": true,
"name": "Time on site: 5 sec",
"rules": [
{
"id": 8201,
"value": "5",
"type": "visit_time_site",
"operator": "equals",
"condition": "and"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, how may I help you?"
}
},
{
"id": 2411,
"active": true,
"name": "Returning visitor",
"rules": [
{
"id": 8191,
"value": "2",
"type": "visits_number",
"operator": "greater_or_equal",
"condition": "and"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello again!"
}
}
]
GET A SINGLE GREETING
Returns the specified greeting.
REQUIRED SCOPES
* greetings_write
ADDITIONAL INFO
* active – Indicates whether the greeting is enabled or not
* rules – Returns an array with all the rules for the specified greeting
GET /greetings/<GREETING_ID>
Copied!
curl "https://api.livechatinc.com/greetings/2411" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"id": 2411,
"active": true,
"name": "Returning visitor",
"rules": [
{
"id": 8191,
"value": "2",
"type": "visits_number",
"operator": "greater_or_equal",
"condition": "and"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello again!"
}
}
CREATE A NEW GREETING
Use this function to create a new greeting.
REQUIRED SCOPES
* greetings_write
REQUIRED PARAMETERS
ParameterDescriptionnamegreeting name displayed in the LiveChat settings (not
visible to your website's visitors)rulesan array of conditions that must be met
for the greeting to be displayed. Greeting rules are documented below
OPTIONAL PARAMETERS
ParameterDescriptiongroupcreates a greeting displayed in a particular group
only. Defaults to 0activecreates a greeting, which is active or inactive.
Defaults to 1subtypepossible values: announcement; you can have up to 10
announcement greetings; if a given announcement greeting is canceled by a
customer, it'll never be displayed to that customer again
POST /greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"my custom invitation",
"rules":[
{
"type":"visit_time_page",
"value":15,
"operator":"greater_than"
},
{
"type":"visits_number",
"value":2,
"operator":"greater_or_equal"
}
]
GREETING RULES
Greeting rules are the conditions that must be met for a greeting to be
displayed.
Each greeting rule can contain an operator. Here's a list of possible operators:
* equals,
* doesnt_equal,
* lower_than,
* lower_or_equal,
* greater_than,
* greater_or_equal,
* contains,
* doesnt_contain.
The default value for operator is equals.
And here's a list of the greeting rules that you can use:
RuleDescriptionvisit_time_siteAfter a visitor has spent a certain amount of time
on the sitevisit_time_pageAfter a visitor has spent a certain amount of time on
a pageurl_currentFor the visitors on specific pagesurl_visitedWhen a visitor has
visited specific pagespages_view_numberFor the visitors who have seen a page for
a number of timesurl_referrerWhen the visitor has arrived from a referring
pagegeolocationFor the visitors from specific countries or
citiesvisits_numberFor the returning visitorssearch_keywordWhen a visitor has
searched for a specific keywordcustom_variableThe greeting will be sent when the
specified variable is met documented belowurl_funnelThe visitors who visit the
specified sequence of websites will receive the greeting documented
belowads_trafficThe greeting will be sent when the customer visits the page
containing ad provider parameters for the first time (per session)
/greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"my custom invitation",
"rules":[
{
"type":"visit_time_page",
"value":15,
"operator":"greater_than"
},
{
"type":"visits_number",
"value":2,
"operator":"greater_or_equal"
}
]
}'
Response
Copied!
{
"id": 2451,
"active": true,
"name": "my custom invitation",
"rules": [
{
"id": 8241,
"value": "2",
"type": "visits_number",
"operator": "greater_or_equal",
"condition": "and"
},
{
"id": 8251,
"value": "15",
"type": "visit_time_page",
"operator": "greater_than",
"condition": "and"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}
CUSTOM VARIABLE
The greeting will be sent when the specified variable is met.
When using the `custom_variable` greeting rule, you also need to provide
`variable_name` and `variable_value`. You also can add the optional `operator`
parameter (defaults to `equals`).
/greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings\
?group=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"custom variable type greeting",
"rules":[
{
"type":"custom_variable",
"variable_name":"my_custom_var",
"variable_value":"var_value"
"operator":"contains"
}
]
}'
Response
Copied!
{
"id": 2431,
"active": true,
"name": "custom variable type greeting",
"rules": [
{
"id": 8221,
"type": "custom_variable",
"operator": "contains",
"condition": "and",
"variable_name": "my_custom_var",
"variable_value": "var_value"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}
ADS TRAFFIC
Available only for licenses with new monitoring solution enabled. The greeting
will be sent when the customer visits the page containing ad provider parameters
for the first time (per session).
When using the ads_traffic greeting rule, you also may provide variable_name and
variable_value. For example, providing variable_name as facebook and
variable_value as 1234 will send the greeting when the customer first visits URL
containing fbclid=1234. You can also add the optional operator parameter
(defaults to equals).
Possible variable_name values are:
* facebook for fbclid,
* google for dclid, gbraid, gclid, gclsrc, wbraid,
* microsoft for msclkid,
* twitter for twclid,
* yahoo for yclid,
The maximum allowed variable_value length is 255 characters.
When not providing variable_name and variable_value, the greeting will be sent
when the customer first visits the URL containing any of the ads parameters.
When providing only variable_name, the greeting will be sent when the customer
first visits the URL containing any of the ads parameters coming from the
provider with the specified name.
When providing only variable_value, the greeting will be sent when the customer
first visits the URL containing any of the ads parameters with the specified
values.
/greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings\
?group=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"ads traffic type greeting",
"rules":[
{
"type":"ads_traffic",
"variable_name":"facebook",
"variable_value":"1234",
"operator":"contains"
}
],
"properties": {
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}'
Response
Copied!
{
"id": 2431,
"active": true,
"name": "ads traffic type greeting",
"rules": [
{
"id": 8221,
"type": "ads_traffic",
"operator": "contains",
"condition": "and",
"variable_name": "facebook",
"variable_value": "1234"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}
URL FUNNEL
The visitors who have visited the specified sequence of pages will receive the
greeting.
When using the `url_funnel` greeting rule, you need to provide the `urls`
variable. It is an array of objects with the required `url` parameter and the
optional `operator` parameter (defaults to: `equals`).
/greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"url funnel type greeting",
"rules":[
{
"type":"url_funnel",
"urls":[
{
"url":"mystore.com/shoes",
"operator":"equals"
},
{
"url":"cart",
"operator":"contains"
}
]
}
]
}'
Response
Copied!
{
"id": 2441,
"active": true,
"name": "url funnel type greeting",
"rules": [
{
"id": 8231,
"type": "url_funnel",
"condition": "and",
"urls": [
{
"url": "mystore.com/shoes",
"operator": "equals"
},
{
"url": "cart",
"operator": "contains"
}
]
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}
GREETINGS WITH MULTIPLE RULES
You can create a greeting that will have more than one rule.
/greetings
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/greetings" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name":"my custom invitation",
"rules":[
{
"type":"visit_time_site",
"value":15
},
{
"type":"custom",
"variable_name":"empty_cart",
"variable_value":true
},
{
"type":"url_current",
"value":"shoes",
"operator":"contains"
}
]
}'
Response
Copied!
{
"id": 2471,
"active": true,
"name": "my custom invitation",
"rules": [
{
"id": 8261,
"type": "custom_variable",
"operator": "equals",
"condition": "and",
"variable_name": "empty_cart",
"variable_value": "true"
},
{
"id": 8271,
"value": "15",
"type": "visit_time_site",
"operator": "equals",
"condition": "and"
},
{
"id": 8281,
"value": "shoes",
"type": "url_current",
"operator": "contains",
"condition": "and"
}
],
"properties": {
"active": "1",
"greeting-message_text": "Hello, would you like to talk about our products?"
}
}
UPDATE A GREETING
You can change the previously created greetings using this request. The
GREETING_ID is obtained from the list of all greetings.
UPDATE GREETING NAME OR MESSAGE
Use this request to change the name or message of a greeting.
REQUIRED SCOPES
* greetings_write
PUT /greetings/<GREETING_ID>
Copied!
curl "https://api.livechatinc.com/greetings/2491" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X PUT -d "name=athletic+shoes&\
properties[greeting-message_text]=Hello"
ACTIVATE AND DEACTIVATE GREETINGS
Activate or deactivate a greeting using this request.
REQUIRED SCOPES
* greetings_write
PUT /greetings/<GREETING_ID>
Copied!
curl "https://api.livechatinc.com/greetings/2491" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X PUT -d "active=0"
CHANGE GREETINGS RULES
Change the rules of your greetings with this request.
REQUIRED SCOPES
* greetings_write
PUT /greetings/<GREETING_ID>
Copied!
curl "https://api.livechatinc.com/greetings/2491"\
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X PUT -d "rules[0][type]=custom_variable&\
rules[0][variable_name]=athletic_shoes&\
rules[0][variable_value]=true"
Response
Copied!
{
"id": 2491,
"active": false,
"name": "athletic shoes",
"rules": [
{
"id": 8371,
"type": "custom_variable",
"operator": "equals",
"condition": "and",
"variable_name": "athletic_shoes",
"variable_value": "true"
}
],
"properties": {
"active": "0",
"greeting-message_text": "Hi, are you looking for some athletic shoes"
}
}
REMOVE A GREETING
Removes a greeting.
REQUIRED SCOPES
* greetings_write
DELETE /greetings/<GREETING_ID>
Copied!
curl "https://api.livechatinc.com/greetings/2491" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"ok": true
}
GROUPS
Please note this API is deprecated. We highly recommend switching to the new
Management APIs.
Use this method to get Agent Groups data and also to create new and modify the
existing Groups.
AVAILABLE PATHS
MethodsPathGET, POST/groupsGET, PUT, DELETE/groups/<GROUP_ID>
LIST ALL GROUPS (DEPRECATED)
We highly recommend switching to the new List Groups method.
Returns all created groups.
REQUIRED SCOPES
* groups--all:ro
Or, groups_read if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
ADDITIONAL INFO
* language specifies the chat window language for the particular group.
* agents list contains all members of the particular group. The group with id 0
doesn't return the agents list because it always contains all agents from the
license and it cannot be modified.
GET /groups
Copied!
curl "https://api.livechatinc.com/groups" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
[
{
"id": 0,
"name": "All operators",
"language": "en",
"status": "accepting chats"
},
{
"id": 1,
"name": "Invoicing",
"language": "en",
"agents": ["jane.doe@mycompany.com"],
"status": "offline"
},
{
"id": 2,
"name": "Sales",
"language": "en",
"agents": ["john.doe@mycompany.com", "jenny.doe@mycompany.com"],
"status": "not accepting chats"
},
{
"id": 3,
"name": "Technical Support",
"language": "en",
"agents": ["john.doe@mycompany.com"],
"status": "accepting chats"
}
]
GET A SINGLE GROUP DETAILS (DEPRECATED)
We highly recommend switching to the new Get Group method.
Returns group details for the given GROUP_ID.
REQUIRED SCOPES
* groups--all:ro
Or, groups_read if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
PARAMETERS
ParameterDescriptionidid of the groupnamegroup namelanguagegroup language
(defaults to English). See the list of supported languagesagentsan array of
group members' loginsstatuscurrent status of the group
ADDITIONAL INFO
The status can take the following values:
* accepting chats – when at least one agent from the group is logged in and has
the accepting chats status.
* not accepting chats – when at least one agent from the group is logged in but
has the not accepting chats status.
* offline – when all agents from the group are offline.
GET /groups/<GROUP_ID>
Copied!
curl "https://api.livechatinc.com/groups/2" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"id": 2,
"name": "Sales",
"language": "en",
"agents": ["john.doe@mycompany.com", "jenny.doe@mycompany.com"],
"status": "accepting chats"
}
CREATE A NEW GROUP (DEPRECATED)
We highly recommend switching to the new Create Group method.
Creates a new group in your license.
REQUIRED SCOPES
* groups--all:rw
Or, groups_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
REQUIRED PARAMETERS
ParameterDescriptionnamegroup nameagentsan array of LiveChat users' logins
(e-mails)
OPTIONAL PARAMETERS
ParameterDescriptionlanguagegroup language (defaults to English). See the list
of supported languages
POST /groups
cURL JSONcURL
Copied!
curl "https://api.livechatinc.com/groups" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"name": "Human Resources",
"agents": [
"jenny.doe@mycompany.com",
"john.doe@mycompany.com"
]
}'
Response
Copied!
{
"id": 4,
"name": "Human Resources",
"language": "en",
"agents": ["jenny.doe@mycompany.com", "john.doe@mycompany.com"],
"status": "offline"
}
UPDATE A GROUP (DEPRECATED)
We highly recommend switching to the new Update Group method.
Updates the specified group by setting the values of the parameters passed. Any
parameters not provided will be left unchanged.
REQUIRED SCOPES
* groups--all:rw
Or, groups_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
OPTIONAL PARAMETERS
ParameterDescriptionnamegroup namelanguagesee the list of supported
languagesagentsan array of LiveChat users' logins (e-mails)
PUT /groups/<GROUP_ID>
cURL JSONcURL
Copied!
curl "https://api.livechatinc.com/groups/3" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 -X PUT \
-H Content-type:application/json \
-d '{
"name": "Quality Assurance",
"agents": [
"john.doe@mycompany.com",
"jane.doe@mycompany.com"
]
}'
Response
Copied!
{
"id": 3,
"name": "Quality Assurance",
"language": "en",
"agents": ["john.doe@mycompany.com", "jane.doe@mycompany.com"],
"status": "offline"
}
REMOVE A GROUP (DEPRECATED)
We highly recommend switching to the new Delete Group method.
Removes a group with the given GROUP_ID.
REQUIRED SCOPES
* groups--all:rw
Or, groups_write if you use the old LiveChat protocol.
💡 Not sure which protocol you use? You use the old one if you don't see the new
scopes in Developer Console.
DELETE /groups/<GROUP_ID>
Copied!
curl "https://api.livechatinc.com/groups/4" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"result": "group removed successfully"
}
STATUS (DEPRECATED)
Please note this API is deprecated. We highly recommend switching to the new
Messaging APIs.
You can use this method to check whether your LiveChat is online or offline.
AVAILABLE PATHS
MethodsPathGET/status
GET STATUS (DEPRECATED)
We highly recommend switching to the new List Routing Statuses method.
Returns the current LiveChat status. Available return values: online, offline.
OPTIONAL PARAMETERS
ParameterDescriptiongroupdefaults to 0
GET /status
Copied!
curl "https://api.livechatinc.com/status/1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"status": "online"
}
TAGS (DEPRECATED)
Please note this API is deprecated. We highly recommend switching to the new
Management APIs.
Using this method, you will be able to create and delete Tags in LiveChat. You
can also use it to learn more about the performance of all your Tags.
AVAILABLE PATHS
MethodsPathGET, POST/tagsDELETE/tags/<TAG>
LIST ALL TAGS
We highly recommend switching to the new List Tags method.
Returns tags from all groups.
REQUIRED SCOPES
* tags_read
OPTIONAL PARAMETERS
ParameterDescriptiongroupreturns tags from chosen group
GET /tags
Copied!
curl "https://api.livechatinc.com/tags\
?group=1" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
[
{
"name": "sales",
"author": "john.doe@mycompany.com",
"creation_date": 1402989014,
"count": {
"inChats": 4,
"inTickets": 1
},
"group": 1
},
{
"name": "support",
"author": "john.doe@mycompany.com",
"creation_date": 1402991857,
"count": {
"inChats": 0,
"inTickets": 2
},
"group": 1
}
]
ADD A TAG (DEPRECATED)
We highly recommend switching to the new Create Tag method.
Adds a new tag. Note that only the owner and the admins are authorized to use
this.
REQUIRED SCOPES
* tags_write
REQUIRED PARAMETERS
ParameterDescriptionauthoragent logintagname of a taggroupid of the group that
tag will be added to
POST /tags
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/tags" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"tag":"support",
"author":"john.doe@mycompany.com",
"group":1
}'
Response
Copied!
{
"name": "support",
"author": "john.doe@mycompany.com",
"creation_date": 1402989014,
"count": {
"inChats": 0,
"inTickets": 0
},
"group": 1
}
DELETE A TAG (DEPRECATED)
We highly recommend switching to the new Delete Tag method.
Deletes a tag from the chosen group. The agents will no longer be able to tag
chats and tickets using this tag.
Deleting a tag will not remove it from the archived chats and tickets.
REQUIRED SCOPES
* tags_write
REQUIRED PARAMETERS
ParameterDescriptiontagtag namegroupid of the group that the tag is assigned to
DELETE /tags/<TAG>
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/tags/support" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 DELETE \
-H Content-type:application/json \
-d '{
"group":1
}'
Response
Copied!
{
"ok": true
}
TICKETS (DEPRECATED)
Please note this API doesn't have its newer equivalent in LiveChat. We highly
recommend migrating to HelpDesk. HelpDesk API Documentation can be found here.
Use this method to get information about a specific case or all Ticket of them.
You also use it to create new Tickets or update tags for the existing Tickets.
AVAILABLE PATHS
MethodsPathGET/tickets/<TICKET_ID>POST/ticketsPUT/tickets/<TICKET_ID>/tags
GET LIST OF TICKETS (DEPRECATED)
Please note that this method doesn't have its newer equivalent in LiveChat. We
highly recommend migrating to HelpDesk. HelpDesk API Documentation can be found
here.
Returns all tickets.
REQUIRED SCOPES
* tickets_read
OPTIONAL PARAMETERS
ParameterDescriptiondate_fromYYYY-MM-DD. Returns the tickets with any of their
activities matching the date. Defaults to the beginning of
timedate_toYYYY-MM-DD. Returns the tickets with any of their activities matching
the date. Defaults to todaypagepage number, defaults to 1assignedif 0, returns
only the unassigned tickets. If 1, returns only the tickets assigned to any
agentorderorders the tickets by date of the last ticket modification. Possible
values: desc, asc. Defaults to descstatusnot set by default. Possible values:
open, pending, solved or spamassigneereturn the tickets assigned to the given
agent's loginqueryreturn the tickets containing the queryrequester[mail]returns
the tickets assigned to the given requestergroupreturns the tickets for the
given groupsourcereturns the tickets for the given source. Possible values: lc2
(created from archives), mail, facebook, agent-app-manual (created manually),
chat-window (created from ticket form)tagreturns the statistics for the
specified tagtagged1/0. If 1 is passed, returns the tickets with any tag. If 0
passed, returns the tickets with no tags
ADDITIONAL INFO
The results are divided into pages, each containing 25 tickets.
total indicates the total number of tickets.
pages indicates the total number of pages.
To access next pages of the results, use ?page=<PAGE> parameter.
Please note that the first page's number is 1, not 0.
GET /tickets
Copied!
curl "https://api.livechatinc.com/tickets?\
date_from=2013-11-15&\
status=open" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"pages": 1,
"total": 15,
"tickets": [
{
"assignee": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"events": [
{
"author": {
"id": "mary.brown@email.com",
"name": "Mary Brown",
"type": "client"
},
"date": 1384554260,
"is_private": false,
"message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
"type": "message",
"source": {
"type": "mail"
}
},
{
"to": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"author": {
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554270,
"type": "assignee_changed"
},
{
"message": "Jane, could you please find a moment to handle this customer's complaint?",
"is_private": true,
"author": {
"type": "agent",
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554322,
"type": "message",
"source": {
"type": "lc2"
}
}
],
"id": "5FUED",
"requester": {
"mail": "mary.brown@email.com",
"name": "Mary Brown"
},
"groups": [0],
"status": "open",
"subject": "My new shoes are broken",
"modified": 1384790802,
"source": {
"type": "mail"
},
"opened": [
{
"from": 1384554260
}
],
"firstResponse": {},
"tags": ["sales", "support", "feedback"]
}
// ...
]
}
GET SINGLE TICKET (DEPRECATED)
Please note that this method doesn't have its newer equivalent in LiveChat. We
highly recommend migrating to HelpDesk. HelpDesk API Documentation can be found
here.
Returns a single ticket item for the given TICKET_ID.
REQUIRED SCOPES
* tickets_read
GET /tickets/<TICKET_ID>
Copied!
curl "https://api.livechatinc.com/tickets/5FUED" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"pages": 1,
"total": 15,
"tickets": [
{
"assignee": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"events": [
{
"author": {
"id": "mary.brown@email.com",
"name": "Mary Brown",
"type": "client"
},
"date": 1384554260,
"is_private": false,
"message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
"type": "message",
"source": {
"type": "mail"
}
},
{
"to": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"author": {
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554270,
"type": "assignee_changed"
},
{
"message": "Jane, could you please find a moment to handle this customer's complaint?",
"is_private": true,
"author": {
"type": "agent",
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554322,
"type": "message",
"source": {
"type": "lc2"
}
}
],
"id": "5FUED",
"requester": {
"mail": "mary.brown@email.com",
"name": "Mary Brown"
},
"groups": [0],
"status": "open",
"subject": "My new shoes are broken",
"modified": 1384790802,
"source": {
"type": "mail"
},
"opened": [
{
"from": 1384554260
}
],
"firstResponse": {},
"tags": ["sales", "support", "feedback"]
}
// ...
]
}
CREATE A TICKET (DEPRECATED)
Please note that this method doesn't have its newer equivalent in LiveChat. We
highly recommend migrating to HelpDesk. HelpDesk API Documentation can be found
here.
Creates a new ticket.
REQUIRED SCOPES
* tickets_write
REQUIRED PARAMETERS
ParameterDescriptionmessagerequester's messagerequester[mail]requester's email
address
OPTIONAL PARAMETERS
ParameterDescriptionrequester[name]requester's nameassignee[id]login of the
agent that will be assigned to the ticketsource[type]source of the ticket.
Possible values: chat-window, mail or lc2. Defaults to lc2source[url]url of the
website that the ticket was sent from. Applies only if source[type] is
chat-windowsubjectticket subject. Defaults to (no subject)grouplist of groups.
Must be an array with group IDs. Defaults to [0]
POST /tickets
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/tickets" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"subject":"I have a problem",
"message":"Hi,I have a problem with my shoes. Could you please advise?",
"requester":
{
"mail":"mary.brown@email.com",
"name":"Mary Brown"
}
}'
Response
Copied!
{
"pages": 1,
"total": 15,
"tickets": [
{
"assignee": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"events": [
{
"author": {
"id": "mary.brown@email.com",
"name": "Mary Brown",
"type": "client"
},
"date": 1384554260,
"is_private": false,
"message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
"type": "message",
"source": {
"type": "mail"
}
},
{
"to": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"author": {
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554270,
"type": "assignee_changed"
},
{
"message": "Jane, could you please find a moment to handle this customer's complaint?",
"is_private": true,
"author": {
"type": "agent",
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554322,
"type": "message",
"source": {
"type": "lc2"
}
}
],
"id": "5FUED",
"requester": {
"mail": "mary.brown@email.com",
"name": "Mary Brown"
},
"groups": [0],
"status": "open",
"subject": "My new shoes are broken",
"modified": 1384790802,
"source": {
"type": "mail"
},
"opened": [
{
"from": 1384554260
}
],
"firstResponse": {},
"tags": ["sales", "support", "feedback"]
}
// ...
]
}
UPDATE TICKET TAGS (DEPRECATED)
Please note that this method doesn't have its newer equivalent in LiveChat. We
highly recommend migrating to HelpDesk. HelpDesk API Documentation can be found
here.
Updates tags associated with the ticket.
REQUIRED SCOPES
* tickets_write
REQUIRED PARAMETERS
ParameterDescriptiontagarray of used tags
PUT /tickets/<TICKET_ID>/tags
cURL (JSON)cURL
Copied!
curl "https://api.livechatinc.com/tickets/5FUED/tags" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-H Content-type:application/json \
-d '{
"tag":["sales","support","feedback"]
}'
Response
Copied!
{
"pages": 1,
"total": 15,
"tickets": [
{
"assignee": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"events": [
{
"author": {
"id": "mary.brown@email.com",
"name": "Mary Brown",
"type": "client"
},
"date": 1384554260,
"is_private": false,
"message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
"type": "message",
"source": {
"type": "mail"
}
}, {
"to": {
"id": "jane.doe@mycompany.com",
"name": "Jane Doe"
},
"author": {
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554270,
"type": "assignee_changed"
}, {
"message": "Jane, could you please find a moment to handle this customer's complaint?",
"is_private": true,
"author": {
"type": "agent",
"id": "john.doe@mycompany.com",
"name": "John Doe"
},
"date": 1384554322,
"type": "message",
"source": {
"type": "lc2"
}
}],
"id": "5FUED",
"requester": {
"mail": "mary.brown@email.com",
"name": "Mary Brown"
},
"groups": [0],
"status": "open",
"subject": "My new shoes are broken",
"modified": 1384790802,
"source": {
"type": "mail"
},
"opened": [{
"from": 1384554260
}],
"firstResponse": {}
},
"tags": [
"sales",
"support",
"feedback"
],
// ...
]
}
WEBHOOKS (DEPRECATED)
We highly recommend switching to the new Management APIs.
This method will help you build your own LiveChat integrations by creating and
managing webhooks.
Check out our webhooks tutorial for more information, use cases and to learn how
to get started.
AVAILABLE PATHS
MethodsPathGET/webhooksPOST/webhooksDELETE/webhooks/<WEBHOOK_ID>
When your server receives a webhook from LiveChat, it should respond with HTTP
200 response. Otherwise, LiveChat will retry sending the webhook to your service
a number of times until it receives the correct HTTP 200 response.
The timeout is set to ~10 seconds. If we don't receive HTTP 200 response within
that time period, we'll retry sending the webhook up to 10 times within 6 hours.
If your endpoint is responsible for both receiving data from our webhook and
making further actions, like creating a record in a database, then the whole
process may take longer than 10 seconds. In such a case, we believe, the best
solution would be to split your mechanism into 2 separate actions:
1) Retrieving data from the LiveChat webhook (sending HTTP 200 back to us
immediately).
2) Further processing of the data and passing it to other services.
That would prevent situations in which the process takes longer than our webhook
timeout and data isn't pushed from our side again.
DISPLAY CONFIGURED WEBHOOKS (DEPRECATED)
We highly recommend switching to the List Webhooks method.
Returns a list of webhooks that have been created in a LiveChat account.
REQUIRED SCOPES
* webhooks_manage
GET /webhooks
Copied!
curl "https://api.livechatinc.com/webhooks" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
Response
Copied!
{
"events": [
{
"licence": 12345,
"event_type": "chat_started",
"data_types": ["chat", "visitor"],
"url": "https://my-company.com/parse_webhook.php",
"verified": true,
"token": "0adec158e423091d5a36c9fce95775db",
"id": "39612eee5f1b431217aafb9de19c1e32"
}
]
}
CREATE A NEW WEBHOOK (DEPRECATED)
We highly recommend switching to the Register Webhook method.
Creates a new webhook.
REQUIRED SCOPES
* webhooks_manage
REQUIRED PARAMETERS
ParameterDescriptionevent_typemust be one of chat_started, chat_ended,
chat_changed, visitor_queued, ticket_created or
canned_response_changeddata_typesdetermines what information the webhook will
containurlthe URL address the webhook will be sent to
ADDITIONAL INFO
event_type determines when the webhook will be sent to your script:
ParameterDescriptionchat_startedwhen the chat is startedchat_endedwhen the chat
is endedchat_changedwhen the chat is taggedvisitor_queuedwhen the visitor enters
the queue before a chatticket_createdwhen a new ticket is
createdcanned_response_changedwhen a canned response is created, modified or
deleted
data_type is an array that includes one or more of the following values):
ParameterDescriptionchatonly supported in chat_started, chat_changed and
chat_ended event typesvisitoronly supported in chat_started, chat_ended,
chat_changed and visitor_queued event typespre_chat_surveyonly supported in
chat_started and chat_ended event typesticketonly supported in ticket_created
event typecanned_responseonly supported in canned_response_changed event type
POST /webhooks
Copied!
curl "https://api.livechatinc.com/webhooks" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2
-d "event_type=chat_started&\
data_types[]=chat&\
data_types[]=visitor&\
url=http://my-company.com/parse_webhook.php
Response
Copied!
{
"events": [
{
"licence": 12345,
"event_type": "chat_started",
"data_types": ["chat", "visitor"],
"url": "https://my-company.com/parse_webhook.php",
"verified": true,
"token": "0adec158e423091d5a36c9fce95775db",
"id": "39612eee5f1b431217aafb9de19c1e32"
}
]
}
DELETE A WEBHOOK (DEPRECATED)
We highly recommend switching to the the Unregister Webhook method.
Deletes a webhook with the given ID.
REQUIRED SCOPES
* webhooks_manage
DELETE /webhooks/<ID>
Copied!
curl "https://api.livechatinc.com/webhooks/39612eee5(...)" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 \
-X DELETE
Response
Copied!
{
"result": "Push notification removed successfully"
}
VISITORS
You can use this method to get information about the real-time Visitors on your
website. You can also use it to display additional information about the
visitors in the LiveChat app.
AVAILABLE PATHS
MethodsPathGET/visitorsPOST/visitors/<VISITOR_ID>/details
LIST ALL VISITORS
Returns a list of the visitors on the pages with the tracking code installed.
REQUIRED SCOPES
* visitors_read
OPTIONAL PARAMETERS
ParameterDescriptionstateparameter determines what state the visitors are.
Possible values: chatting, queued, browsing, invited, refused invitation or chat
closedgroup[]parameter decides which group will be used for the listing. Use
group numbers as values to select visitors only for the specified
groupcountparameter will allow you to return the number of visitors (when the
value is set to 1) instead of all the available information (when it is set to
0). The parameter is set to 0 by default
ADDITIONAL INFO
The possible state values returned without any filter are:
* browsing
* chatting
* logging into chat
* queued
* invited
* refused invitation
* chat closed
The possible state filter values are chatting and queued.
prechat_survey parameter will be available only if the visitor is currently
chatting.
custom_variables parameter will be available only if the custom variables are
defined in the tracking code.
GET /visitors
Copied!
curl "https://api.livechatinc.com/visitors?
state=chatting&\
group[]=0" \
-H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
-H X-API-Version:2 -g
Response
Copied!
[
{
"browser": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
"chat": {
// (...)
},
"chat_id": "DL1G0UED4H",
"chat_start_time": "2017-02-16 12:54:26",
"chat_start_time_ts": 1487246066,
"chats": 1,
"custom_variables": [
{
"key": "empty_cart",
"value": "true"
}
],
"city": "Greenville",
"country": "United States",
"country_code": "US",
"greetings_accepted": 1,
"greetings_all": 2,
"greetings_refused": 1,
"group": 102,
"host": "very-hosty.sl.us",
"id": "S148dea44981.d9443253fef2",
"invitation": "",
"ip": "8.8.8.8",
"language": "en",
"last_visit": "2017-02-16 12:36:21",
"last_visit_ts": 1487244981,
"latitude": "35.6127",
"longitude": "-77.3663",
"name": "Visitor",
"operators": [
// (...)
],
"page_address": "https://platform.text.com/docs/extending-chat-widget/javascript-api/",
"page_current": "https://platform.text.com/docs/extending-chat-widget/javascript-api/",
"page_entered": "2017-02-16 12:36:21",
"page_entered_ts": 1487244981,
"page_time": "2017-02-16 12:39:12",
"page_time_ts": 1487245152,
"page_title": "LiveChat – Chat Window API (JS)",
"page_views": 16,
"prechat_survey": [
// (...)
],
"queue_start_time": 46843480,
"referrer": "https://www.livechat.com/",
"region": "North Carolina",
"state": "chatting",
"timezone": "America/New_York",
"visit_path": [
{
"invitation": "Time on site: 30 sec",
"page": "https://platform.text.com/docs/",
"time": "2017-02-16 12:36:21",
"time_ref": 1487244981,
"time_ts": 1487244981,
"title": "LiveChat Developers - REST API & Integrations"
},
{
"invitation": "",
"page": "https://platform.text.com/docs/",
"time": "2017-02-16 12:38:33",
"time_ref": 1487245113,
"time_ts": 1487245113,
"title": "LiveChat Platform Docs"
}
// (...)
],
"visits": 3
}
// (...)
]
Was this page helpful?
Join the community
Get in direct contact with us through Discord.
Discord
Follow us
Follow our insightful tweets and interact with our content.
Twitter
Contribute
See something that's wrong or unclear? Submit a pull request.
GitHub
Contact us
Want to share feedback? Reach us at: developers@livechat.com