Welcome to the LiveChat API documentation! Our API provides flexible tools that can be used in the creation of new, outstanding projects. Each time we see creative development by skilled engineers we smile a bit more!
Please note that this documentation refers to the latest, API 2.0 version. If you are looking for the previous version, you might want to check the deprecated API 1.0 documentation.
All LiveChat API requests start with https://api.livechatinc.com/.
The next segment of the URI path depends on the type of request. For example:
https://api.livechatinc.com/agents
to get or modify agents data.
All requests must have X-API-VERSION header set to number of the version that you'd like to use. The most recent version is 2.
curl -u LOGIN:API_KEY -H X-API-Version:VERSION URL
You must use your login and API_KEY for each method call.
You'll find your API_KEY in your LiveChat profile.
Authentication to the API occurs via HTTP Basic Auth.
Provide your login as the basic auth username and the API_KEY as the password. You must authenticate for all requests.
All API requests must be made over HTTPS.
For example, if your login is john.doe@mycompany.com, your API key is c14b85863755158d7aa5cc4ba17f61cb and you want to invoke the agents API method, your request will look like:
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/agents
LiveChat API returns data in JSON format. Example agents list returned in this format:
[
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
{
"name": "Jane Doe",
"permission": "normal",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/a557c601619878e28343cddb9a1b8445.jpg",
"login": "jane.doe@mycompany.com",
"status": "offline"
}
]
All requests made with HTTP GET are JSONP-enabled. To use JSONP, append callback= and the name of your callback function to the request.
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb https://api.livechatinc.com/operators?callback=example
example([
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
{
"name": "Jane Doe",
"permission": "normal",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/a557c601619878e28343cddb9a1b8445.jpg",
"login": "jane.doe@mycompany.com",
"status": "offline"
}
])
Errors are returned using standard HTTP error code syntax. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error (bad or missing parameters, not authenticated etc.), and codes in the 5xx range indicate an error with LiveChat's servers. Any additional info is included in the body of the return call, JSON-formatted.
400 – The request was incorrect, please make sure that passed arguments are matching format in method's documentation.401 – Unauthorized. You attempt to authenticate with an invalid username or API key.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 support.Use this integration to manage your agents. This function can also be used to get information regarding your agents.
[GET|POST] /agents
[GET|PUT|DELETE] /agents/<LOGIN>
[POST] /agents/<LOGIN>/reset_api_key
Returns all LiveChat agents list.
Additional info:
status can be: accepting chats, not accepting chats or offline.
permission can take the following values: owner, administrator, normal.
GET https://api.livechatinc.com/agents
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/agents
[
{
"name": "John Doe",
"permission": "owner",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
"login": "john.doe@mycompany.com",
"status": "accepting chats"
},
{
"name": "Jane Doe",
"permission": "normal",
"avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/a557c601619878e28343cddb9a1b8445.jpg",
"login": "jane.doe@mycompany.com",
"status": "offline"
}
]
Return complete details of the agent for the given LOGIN.
Attributes:
login – the agent's e-mail address.name – the agent's name.login_status – possible values: accepting chats, not accepting chats, offline.permission – possible values: owner, administrator, normal.daily_summary – whether or not the agent receive daily summary.job_title – defaults to: Support Agent.avatar – path to the image on Amazon s3.notifications – whether or not the specific notification is enabled.max_chats_count – limit of the concurrent chats.groups[] – list of groups the agent is a member of.status – possible values: accepting chats, not accepting chats, offline.last_logout – timestamp of the agent's last logout.
api_key – the agent's API key.
GET https://api.livechatinc.com/agents/<LOGIN>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/agents/john.doe@mycompany.com
{
"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,
"api_key": "6ed8580f2cc160ce98d16389a0ede2c0"
}
Creates a new agent in your license.
Required properties:
login – must be correct e-mail address.nameOptional properties:
job_title – defaults to: Support Agent.login_status – possible values: accepting chats (default), not accepting chats.password – the minimum length is 5 (if not provided, an email with the activation link will be sent).permission – administrator, normal (default).groups[] – list of group IDs.notifications – object (allowed keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, new_goal, allowed values: 0 or 1).daily_summary – 0 or 1 (default).max_chats_count – defaults to 6.POST https://api.livechatinc.com/agents
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -d "login=jenny.doe@mycompany.com&name=Jenny+Doe&permission=administrator&groups[]=1&groups[]=2¬ifications["new_visitor"]=1¬ifications["new_goal"]=1" https://api.livechatinc.com/agents
{
"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,
"api_key": "441e519f755db8a51a4e232a31fe6249"
}
Updates the specified agent by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
All properties are optional:
job_titlenamelogin_status – accepting chats (default), not accepting chats.password – the minimum length is 5.current_password – required when setting a new passwordpermission – administrator, normal (default).status – accepting chats, not accepting chats, offline.groups[] – list of group IDs.notifications – object (allowed keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, new_goal, allowed values: 0 or 1).daily_summary – 0 or 1.max_chats_countProperties agent can edit on his own profile, without being an administrator:
passwordnamejob_titledaily_summarynotificationslogin_statusstatusPUT https://api.livechatinc.com/agents/<LOGIN>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X PUT -d "status=not+accepting+chats&max_chats_count=2" https://api.livechatinc.com/agents/jenny.doe@mycompany.com
{
"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,
"groups": [
{
"id": 1,
"name": "Sales"
},
{
"id": 2,
"name": "Technical Support"
}
],
"status": "not accepting chats",
"last_logout": 0,
"api_key": "441e519f755db8a51a4e232a31fe6249"
}
Reset API key for the agent with given LOGIN.
PUT https://api.livechatinc.com/agents/<LOGIN>/reset_api_key
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X PUT https://api.livechatinc.com/agents/jenny.doe@mycompany.com/reset_api_key
Return format is the same as in update agent method.
Removes an agent. Archived chats will not be removed, but all statistics will be lost. Agent will be notified by e-mail that the account has been deleted.
DELETE https://api.livechatinc.com/agents/<LOGIN>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X DELETE https://api.livechatinc.com/agents/jenny.doe@mycompany.com
{
"result": "jenny.doe@mycompany.com removed successfully"
}
This function allows you to get a full list of your canned responses and change them.
[GET|POST] /canned_responses
[GET|PUT|DELETE] /canned_responses/<CANNED_RESPONSE_ID>
Returns list of all currently set canned responses.
Optional parameter:
group – defaults to 0.Additional info:
If the canned response was modified, it has additional modification_date and modified_by parameters.
GET https://api.livechatinc.com/canned_responses
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/canned_responses?group=1
[
{
"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"
]
},
{
"id": 3171,
"group": 1,
"text": "I will transfer you to the agent responsible for this matter.",
"creation_date": 1358864376,
"created_by": "jenny.doe@mycompany.com",
"tags": [
"transfer",
"matter"
]
}
]
CANNED_RESPONSE_ID is obtained from the all canned responses list.
Attributes:
id – id of the canned response.group – id of the group that canned response is assigned to.text – canned response text.creation_date – creation date timestamp.created_by – login of the canned response's author.tags – an array of canned response's tags.GET https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/canned_responses/3151
{
"id": 3151,
"group": 1,
"text": "Can I help you with anything else?",
"creation_date": 1358257181,
"created_by": "john.doe@mycompany.com",
"tags": [
"help",
"else"
]
}
Creates a new canned response.
Required parameters:
text – response text.tags – array of strings (tags)Optional properties:
group – defaults to 0.POST https://api.livechatinc.com/canned_responses
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -d "text=Have+a+great+day,+goodbye.&tags[]=bye&tags[]=cu" https://api.livechatinc.com/canned_responses
{
"id": 3181,
"group": 0,
"text": "Have a great day, goodbye.",
"creation_date": 1358866421,
"created_by": "john.doe@mycompany.com",
"tags": [
"cu",
"bye"
]
}
Updates the specified canned response by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Optional parameters:
text – response text.tags – array of strings (tags).PUT https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X PUT -d "tags[]=bye" https://api.livechatinc.com/canned_responses/3181
{
"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"
]
}
Removes a canned response with the given CANNED_RESPONSE_ID.
DELETE https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X DELETE https://api.livechatinc.com/canned_responses/3181
{
"result": "Canned response removed successfully"
}
Get finished chats and left messages by using the "type" parameter of this function. Additionally, you can also use it to send chat transcripts.
[GET] /chats
[GET] /chats/<CHAT_ID>
[POST] /chats/<CHAT_ID>/send_transcript
Returns all ended chats.
Optional parameters:
date_from – YYYY-MM-DD. Defaults to the beginning of time.date_to – YYYY-MM-DD. Defaults to today.type – type of chats, not set by default. Available values: chat, missed_chat.page – page number, defaults to 1.visitor_id – return chats with specified visitor_id.query – return chats containing the query.agent – return chats for given agent login.group – return chats for given group.goal – return chats for given goal id.has_goal – 1/0. If 1 is passed, returns chats having any goal.rate – filter chats considering its rating status. Available values: rated, not_rated, rated_good, rated_bad.
Additional info:
goal parameter will appear only if a goal for a particular chat has been reached.custom_variables parameter will be available only if the custom variables are defined in the tracking code.
integration_variables parameter will appear only if a visitor logs in with Facebook.
Results are divided into pages, each containing 25 chats.
total tells you the total number of chats.pages tells you the total number of pages.
To access next pages of the results, use ?page=<PAGE> parameter.
Please note that first page's number is 1, not 0.
GET https://api.livechatinc.com/chats
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/chats?date_from=2013-01-23&has_goal=1
{
"chats": [
{
"type": "chat",
"id": "MH022RD0K5",
"visitor_name": "Mary Brown",
"visitor_id": "S1355415390.49b8940793",
"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, // in seconds
"group": [
0
],
"started": "Wed, 01/23/13 11:40:53 am",
"prechat_survey": [
{
"key": "Name:",
"value": "",
"id": "13589376348060238"
},
{
"key": "E-mail:",
"value": "",
"id": "135893763480606511"
}
],
"custom_variables": [
{
"key": "customer_login",
"value": "mary_brown"
}
],
"integration_variables": [
{
"key": "facebook.id",
"value": "123456789"
},
{
"key": "facebook.name",
"value": "Mary Brown"
},
{
"key": "facebook.first_name",
"value": "Mary"
},
{
"key": "facebook.last_name",
"value": "Brown"
},
{
"key": "facebook.gender",
"value": "female"
},
{
"key": "facebook.locale",
"value": "en_US"
},
{
"key": "facebook.link",
"value": "http://www.facebook.com/mary.brown"
},
{
"key": "facebook.username",
"value": "mary.brown"
},
{
"key": "facebook.email",
"value": "mary.brown@email.com"
}
],
"goals": [
{
"id": 71,
"name": "goal_name"
}
],
"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"
},
{
"author_name": "Mary Brown",
"text": "How are you?",
"date": "Wed, 01/23/13 11:41:01 am",
"timestamp": 1358937661,
"user_type": "visitor"
},
{
"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"
},
{
"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"
}
],
"started_timestamp": 1358937653,
"ended_timestamp": 1358939109,
"ended": "Wed, 01/23/13 12:05:09 pm"
},
{
...
}
],
"total": 2,
"pages": 1
}
Returns single chat item for the given CHAT_ID.
GET https://api.livechatinc.com/chats/<CHAT_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/chats/MH022RD0K5
Return format is the same as the single chat item in chats list.
Required parameter:
to – receiver's email address.POST https://api.livechatinc.com/chats/<CHAT_ID>/send_transcript
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -d "to=john.doe@mycompany.com" https://api.livechatinc.com/chats/MH022RD0K5/send_transcript
{
"result": "E-mail has been sent to john.doe@mycompany.com."
}
Pull information regarding your goals and manage them using this function.
[GET|POST] /goals
[GET|PUT|DELETE] /goals/<GOAL_ID>
[POST] /goals/<GOAL_ID>/mark_as_successful
Returns all currently set goals.
Additional info:
active tells you if the particular goal is enabled or not.GET https://api.livechatinc.com/goals
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/goals
[
{
"id": 1041,
"name": "purchase",
"active": 1
},
{
"id": 1181,
"name": "nike shoes variable",
"active": 1
}
]
Returns goal details for the given GOAL_ID.
Attributes:
id – id of the goal.name – goal name.active – whether or not the goal is enabled.type – type of the goal.Additional info:
type 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 – without any additional parameters.
GET https://api.livechatinc.com/goals/<GOAL_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/goals/1181
{
"id": 1181,
"name": "nike shoes variable",
"active": 1,
"type": "custom_variable",
"custom_variable_name": "nike_shoes",
"custom_variable_value": "true"
}
GOAL_ID is obtained from the goals list.
Required parameter:
visitor_id – obtained using JavaScript API: LC_API.get_visitor_id().Optionally you can store additional information regarding the goal. They can be only retrieved using the API.
order_id – for example: ''AP723HVCA721''order_description – for example: ''Nike shoes''order_price – for example: ''199.00''order_currency – for example: ''USD''POST https://api.livechatinc.com/goals/<GOAL_ID>/mark_as_successful
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -d "visitor_id=S1281361958.2238ee3bd3" https://api.livechatinc.com/goals/1181/mark_as_successful
{
"result": "goal marked as successful"
}
Creates new goal.
Required parameters:
nametypeAdditional info:
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 – without any additional parameters.
active parameter tells you if the goal is active or not.
POST https://api.livechatinc.com/goals
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-VERSION:2 -d "name=new%20goal&type=url&url=http://www.mystore.com/checkout/thank_you&match_type=exact" https://api.livechatinc.com/goals
{
"id": 2231,
"name": "new goal",
"active": 1,
"type": "url",
"match_type": "exact",
"url": "http://www.mystore.com/checkout/thank_you"
}
Updates the specified goal by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
GOAL_ID is obtained from the goals list.
All parameters are optional:
nametypeAdditional info:
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 – without any additional parameters.
active parameter tells you if the goal is active or not.
PUT https://api.livechatinc.com/goals/<GOAL_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X PUT -d "name=new%20goal%20paused&active=0" https://api.livechatinc.com/goals/2231
{
"id": 2231,
"name": "new goal paused",
"active": 0,
"type": "url",
"match_type": "exact",
"url": "http://www.mystore.com/checkout/thank_you"
}
Removes a goal with the given GOAL_ID.
DELETE https://api.livechatinc.com/goals/<GOAL_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X DELETE https://api.livechatinc.com/goals/2231
{
"result": "goal removed successfully"
}
Manage your groups and group-related data using this function.
[GET|POST] /groups
[GET|PUT|DELETE] /groups/<GROUP_ID>
Returns all created groups.
Additional info:
language tells you the chat window language for the particular skill. See the list of supported languages.
agents list contains all members of the particular group. Group with id 0 doesn't return agents list because it always contains all agents from the license and it cannot be modified.
GET https://api.livechatinc.com/groups
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/groups
[
{
"id": 0,
"name": "All operators",
"language": "en"
},
{
"id": 1,
"name": "Invoicing",
"language": "en",
"agents": [
"jane.doe@mycompany.com"
]
},
{
"id": 2,
"name": "Sales",
"language": "en",
"agents": [
"john.doe@mycompany.com",
"jenny.doe@mycompany.com"
]
},
{
"id": 3,
"name": "Technical Support",
"language": "en",
"agents": [
"john.doe@mycompany.com"
]
}
]
Returns group details for the given GROUP_ID.
Attributes:
id – id of the group.name – group name.language – group language (defaults to English). See the list of supported languages.agents – an array of group members' logins.status – current status of the group.Additional info:
status can take the following values:
accepting chats – when at least one agent from the group is logged in and in accepting chats status.not accepting chats – when at least one agent from the group is logged in but in not accepting chats status.offline – when all agents from the group are offline.GET https://api.livechatinc.com/groups/<GROUP_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/groups/2
{
"id": 2,
"name": "Sales",
"language": "en",
"agents": [
"john.doe@mycompany.com",
"jenny.doe@mycompany.com"
],
"status": "accepting chats"
}
Creates a new group in your license.
Required properties:
name – group name.agents – an array of LiveChat users' logins (e-mails).Optional properties:
language – group language (defaults to English). See the list of supported languages.POST https://api.livechatinc.com/groups
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -d "name=Human+Resources&agents[0]=jenny.doe@mycompany.com&agents[1]=john.doe@mycompany.com" https://api.livechatinc.com/groups
{
"id": 4,
"name": "Human Resources",
"language": "en",
"agents": [
"jenny.doe@mycompany.com",
"john.doe@mycompany.com"
],
"status": "offline"
}
Updates the specified group by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Optional properties:
name – group name.language – see the list of supported languages.agents – an array of LiveChat users' logins (e-mails).PUT https://api.livechatinc.com/groups/<GROUP_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X PUT -d "name=Quality+Assurance&agents[0]=john.doe@mycompany.com&agents[1]=jane.doe@mycompany.com" https://api.livechatinc.com/groups/3
{
"id": 3,
"name": "Quality Assurance",
"language": "en",
"agents": [
"john.doe@mycompany.com",
"jane.doe@mycompany.com"
],
"status": "offline"
}
Removes a group with the given GROUP_ID.
DELETE https://api.livechatinc.com/groups/<GROUP_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 -X DELETE https://api.livechatinc.com/groups/4
{
"result": "group removed successfully"
}
Pull various metrics and reporting data using this function.
[GET] /reports/dashboard
[GET] /reports/dashboard/agent/<LOGIN>
[GET] /reports/dashboard/group/<GROUP_ID>
[GET] /reports/chats
[GET] /reports/ratings
[GET] /reports/ratings/ranking
[GET] /reports/queued_visitors
[GET] /reports/queued_visitors/waiting_times
[GET] /reports/availability
[GET] /reports/goals
Returns statistics overview from last 7 days for the whole license.
Includes chats and missed chats (offline messages), goals, queues, ratings and agents ranking (the ratio of good to bad ratings for each agent).
GET https://api.livechatinc.com/reports/dashboard
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/dashboard
{
"chats": {
"2013-01-23": {
"chats": 480,
"missed_chats": 1
},
"2013-01-24": {
"chats": 478,
"missed_chats": 0
},
"2013-01-25": {
"chats": 390,
"missed_chats": 5
},
"2013-01-26": {
"chats": 0,
"missed_chats": 102
},
"2013-01-27": {
"chats": 0,
"missed_chats": 104
},
"2013-01-28": {
"chats": 451,
"missed_chats": 0
},
"2013-01-29": {
"chats": 184,
"missed_chats": 0
}
},
"ranking": {
"ranking": [
{
"good": 46,
"bad": 3,
"total": 49,
"score": 0.8015175735455089,
"name": "john.doe@mycompany.com"
},
{
"good": 44,
"bad": 5,
"total": 49,
"score": 0.7449802727393533,
"name": "jenny.doe@mycompany.com"
},
{
"good": 33,
"bad": 5,
"total": 38,
"score": 0.6848967856132273,
"name": "jane.doe@mycompany.com"
}
]
},
"goals": 12,
"queues": 198,
"ratings": {
"good": 154,
"bad": 24
}
}
LOGIN must be correct e-mail address.
Returns statistics overview from last 7 days for the specified agent. Shows his ratings, number of chats and number of reached goals.
GET https://api.livechatinc.com/reports/dashboard/agent/<LOGIN>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/dashboard/agent/john.doe@mycompany.com
{
"ratings": {
"good": 230,
"bad": 5
},
"chats": 336,
"goals": 4
}
GROUP_ID is obtained from all groups list.
Returns statistics overview from last 7 days for the specified group. Shows ratings, number of chats and reached goals.
GET https://api.livechatinc.com/reports/dashboard/group/<GROUP_ID>
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/dashboard/group/2
{
"goals": 6,
"chats": 1916,
"ratings": {
"good": 148,
"bad": 23
}
}
Shows how many chats and missed chats (offline messages) occurred during the specified period.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.agent – agent's login, not set by default, return statistics for the specified agent.group_by – defaults to day (or hour when date_from equals date_to), can be set to month or hour.GET https://api.livechatinc.com/reports/chats
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/chats?date_from=2013-01-29&date_to=2013-01-29&agent=john.doe@mycompany.com&group_by=hour
{
"00:00": {
"chats": 18,
"missed_chats": 0
},
"01:00": {
"chats": 19,
"missed_chats": 0
},
"02:00": {
"chats": 6,
"missed_chats": 0
},
"03:00": {
"chats": 15,
"missed_chats": 0
},
"04:00": {
"chats": 10,
"missed_chats": 0
},
"05:00": {
"chats": 14,
"missed_chats": 0
},
"06:00": {
"chats": 11,
"missed_chats": 0
},
(...)
"21:00": {
"chats": 0,
"missed_chats": 0
},
"22:00": {
"chats": 0,
"missed_chats": 0
},
"23:00": {
"chats": 2,
"missed_chats": 0
}
}
Shows how many chats were rated and how they have been rated during specified period.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.agent – agent's login, not set by default, return statistics for the specified agent.group_by – defaults to day (or hour when date_from equals date_to), can be set to month or hour.GET https://api.livechatinc.com/reports/ratings
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/ratings?group=2&date_from=2012-01-29&date_to=2013-01-29&group_by=month
{
"2012-01": {
"begin": "2012-01-29",
"end": "2012-01-31",
"bad": 0,
"good": 6,
"chats": 37
},
"2012-02": {
"begin": "2012-02-01",
"end": "2012-02-29",
"bad": 4,
"good": 38,
"chats": 320
},
"2012-03": {
"begin": "2012-03-01",
"end": "2012-03-31",
"bad": 0,
"good": 16,
"chats": 186
},
(...)
"2012-11": {
"begin": "2012-11-01",
"end": "2012-11-30",
"bad": 20,
"good": 49,
"chats": 389
},
"2012-12": {
"begin": "2012-12-01",
"end": "2012-12-31",
"bad": 22,
"good": 35,
"chats": 419
},
"2013-01": {
"begin": "2013-01-01",
"end": "2013-01-29",
"bad": 18,
"good": 51,
"chats": 559
}
}
Shows the ratio of good to bad ratings for each operator.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.GET https://api.livechatinc.com/reports/ratings/ranking
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/ratings/ranking
{
"ranking": [
{
"good": 2502,
"bad": 426,
"total": 2928,
"score": 0.8361489669658251,
"name": "john.doe@mycompany.com"
},
{
"good": 2164,
"bad": 443,
"total": 2607,
"score": 0.8094273999034496,
"name": "jane.doe@mycompany.com"
},
{
"good": 1070,
"bad": 215,
"total": 1285,
"score": 0.8029689181922964,
"name": "jenny.doe@mycompany.com"
}
}
Shows how many visitors were waiting in the queue, how many abandoned the queue or proceeded to chats.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.group_by – defaults to day (or hour when date_from equals date_to), can be set to month or hour.
GET https://api.livechatinc.com/reports/queued_visitors
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/queued_visitors?date_from=2013-01-29&group=2
{
"2013-01-29": {
"queued": {
"count": 6,
},
"left_queue": {
"count": 3,
},
"entered_chat": {
"count": 3,
}
},
"2013-01-30": {
"queued": {
"count": 2,
},
"left_queue": {
"count": 0
},
"entered_chat": {
"count": 2,
}
}
}
Shows Minimum, Average and Maximum waiting time.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.group_by – defaults to day (or hour when date_from equals date_to), can be set to month or hour.
GET https://api.livechatinc.com/reports/queued_visitors/waiting_times
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/queued_visitors/waiting_times?date_from=2013-01-29&group=2
{
"2013-01-29":{
"queued":{
"min":{
"seconds":0
},
"max":{
"seconds":112
},
"average":{
"seconds":24
}
},
"left_queue":{
"min":{
"seconds":33
},
"max":{
"seconds":56
},
"average":{
"seconds":44
}
},
"entered_chat":{
"min":{
"seconds":10
},
"max":{
"seconds":112
},
"average":{
"seconds":23
}
}
}
}
Shows how much the agent (or group or whole account) was available for chatting during specified period. When querying for one day results are shown in minutes per every hour, otherwise in hours for each day.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.agent – agent's login, not set by default, return statistics for the specified agent.Results are grouped by hours when querying for single day, grouped by days otherwise.
GET https://api.livechatinc.com/reports/availability
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/availability?date_from=2013-01-25&date_to=2013-01-30&agent=john.doe@mycompany.com&group_by=day
{
"2013-01-25": {
"hours": 0
},
"2013-01-26": {
"hours": 0
},
"2013-01-27": {
"hours": 0.01
},
"2013-01-28": {
"hours": 7.85
},
"2013-01-29": {
"hours": 7.99
},
"2013-01-30": {
"hours": 2.28
}
}
Shows how much time the agent (or group) spent on chatting during specified period. When querying for one day results are shown in minutes per every hour, otherwise in hours for each day.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.agent – agent's login, not set by default, returns statistics for the specified agentGET https://api.livechatinc.com/reports/chatting_time
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/chatting_time?date_from=2013-01-25&date_to=2013-01-30&group=1
{
"2013-01-25": {
"hours": 8.17
},
"2013-01-26": {
"hours": 9.2
},
"2013-01-27": {
"hours": 5.3
},
"2013-01-28": {
"hours": 7.16
},
"2013-01-29": {
"hours": 10.71
},
"2013-01-30": {
"hours": 6.51
}
}
Shows the number of reached goals.
Optional arguments:
date_from – YYYY-MM-DD, defaults to the beginning of time.date_to – YYYY-MM-DD, defaults to today.group – id of the group, not set by default, returns statistics for the specified group.agent – agent's login, not set by default, return statistics for the specified agent.group_by – defaults to day (or hour when date_from equals date_to), can be set to month or hour.GET https://api.livechatinc.com/reports/goals
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/reports/goals?date_from=2013-01-01&goal=71&group_by=month
{
"2013-01": {
"begin": "2013-01-01",
"end": "2013-01-30",
"goals": 4
}
}
This function will allow you to know the current status of your live chat.
[GET] /status
Returns current LiveChat status.
Available return values: online, offline.
Optional parameter:
group – defaults to 0.GET https://api.livechatinc.com/status
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/status/1
{
"status":"online"
}
Use this function to get visitor-related information.
[GET] /visitors
[GET] /visitors/chatting
[POST] /visitors/<VISITOR_ID>/details
Returns list of the visitors available on pages with tracking code installed.
Additional info:
Possible state values are:
onlinequeuedinvitedinvitation refusedchattingclosedprechat_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 https://api.livechatinc.com/visitors
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/visitors
[
{
"browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_2) AppleWebKit/536.26.14 (KHTML, like Gecko) Version/6.0.1 Safari/536.26.14",
"chat_id": "MH0H3V3XO3",
"chat_start_time": "2013-01-31 15:51:03",
"city": "Greenville",
"country": "United States",
"host": "152.27.26.254",
"id": "S1355415390.49b8940793",
"ip": "152.27.26.254",
"language": "en",
"last_visit": "2013-01-31 15:43:05",
"latitude": "35.6127",
"longitude": "-77.3663",
"operators": [
{
"id": "john.doe@mycompany.com",
"display_name": "John Doe"
}
],
"page_current": "http://www.mycompany.com/products/shoes",
"page_entered": "2013-01-31 15:49:17",
"page_time": "2013-01-31 15:49:17",
"prechat_survey": [
{
"key": "Name:",
"value": "Mark"
},
{
"key": "E-mail:",
"value": "mark.johnson@example.com"
}
],
"queue_start_time": "",
"referrer": "",
"region": "North Carolina",
"state": "chatting",
"timezone": "America/New_York",
"custom_variables": [
{
"key": "empty_cart",
"value": "true"
}
],
"chats": 27,
"group": 0,
"greetings_accepted": 9,
"greetings_all": 13,
"greetings_refused": 4,
"visits": 16,
"page_views": 59
},
{
"browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.11 (KHTML, like Gecko) Chrome/23.0.1271.101 Safari/537.11",
"chat_id": "",
"chat_start_time": "",
"city": "Courbevoie",
"country": "France",
"host": "def92-2-87-91-13-226.dsl.sta.abo.bbox.fr",
"id": "S1359643767.a7904dd2f2",
"ip": "87.91.13.226",
"language": "en",
"last_visit": "2013-01-31 15:49:27",
"latitude": "48.897",
"longitude": "2.2564",
"operators": [
{
"id": "",
"display_name": ""
}
],
"page_current": "http://www.mycompany.com/",
"page_entered": "2013-01-31 15:49:27",
"page_time": "2013-01-31 15:49:27",
"prechat_survey": [
],
"queue_start_time": "",
"referrer": "",
"region": "Ile-de-France",
"state": "online",
"timezone": "Europe/Paris",
"chats": 0,
"group": 0,
"greetings_accepted": 0,
"greetings_all": 0,
"greetings_refused": 0,
"visits": 1,
"page_views": 1
},
(...)
]
Returns list of currently chatting visitors.
GET https://api.livechatinc.com/visitors/chatting
curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb -H X-API-Version:2 https://api.livechatinc.com/visitors/chatting
Return format is the same as in visitors list.
Displays additional information about the visitor in LiveChat apps.
For example, if you have your own database with additional details about your users, you can look up this database based on your visitor’s e-mail address, and display the information from your database for the agent during the chat.
Note: this method can only be used along with the Webhooks. You should create a webhook with chat_started event that will be sent to your integration script. This script must read webhook's license_id and token params and include them in this API method call. See an example integration in Webhooks documentation.
Required properties:
license_id – sent by the webhook (read the note above).token – sent by the webhook (read the note above).id – descriptive ID your data set, for example: "my-app". It lets us group the data into one set and display many different data sets for single visitor. It should include only alphanumeric characters (letters, digits, punctuation marks).fields – array of data objects that include name and value properties. This is the actual data that you have about your visitor. This data will be displayed to the agent during the chat.Optional properties:
icon – address of the icon picture that will be displayed in the LiveChat app next to visitor’s data. It lets you group important information.icon should be a URL without the http:// prefix. Your web server should support serving the icon file using https:// (SSL) protocol. The icon’s dimensions must be 64x64 px.POST https://api.livechatinc.com/visitors/<VISITOR_ID>/details
curl -H X-API-Version:2 https://api.livechatinc.com/visitors/S1352647457.ac951bfe2e/details -X POST -d "license_id=12345&token=26132406c42c96ba61ed42689b70f719&id=my-app&fields[0][name]=Age&fields[0][value]=36"
{
"result": "Visitor details added"
}