Introduction

Welcome to the LiveChat API documentation! Our API provides flexible tools you can use to create new, outstanding projects. We smile a bit more each time we see creative development by skilled engineers!

Please note that this documentation refers to the latest API version: 2.0. If you are looking for the previous version, you might want to check the deprecated API 1.0 documentation.

Basic API usage

Example method call

curl -u LOGIN:API_KEY -H X-API-Version:VERSION URL

All LiveChat API requests start with https://api.livechatinc.com/.

Connection endpoint

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.

Authentication

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 "https://api.livechatinc.com/agents" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

You must use your login and API_KEY for each method call. You'll find it 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.

Data format

Example agents list returned in 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"
  },
  ...
]

LiveChat API returns data in JSON format. See the following example.

JSONP

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

Example 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

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.

HTTP status codes summary

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.

Cross-domain

All cross-domain API requests made by a web browser are denied for security reasons. It means that browser-based requests are not allowed from 3rd party domains (including localhost).

LiveChat API libraries

All API calls include an API key that could be easily stolen when making a request using a web browser. It means you should use backend languages for API requests. See the list of ready-to-use libraries:

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.

Agents

Use this API method to manage your Agents and to get information about their activities.

Available paths

Methods	Path
`GET`, `POST`	`/agents`
`GET`, `PUT`, `DELETE`	`/agents/<LOGIN>`
`POST`	`/agents/<LOGIN>/reset_api_key`

List all agents

Path

GET https://api.livechatinc.com/agents

Example request

curl "https://api.livechatinc.com/agents" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

[
  {
    "name": "John Doe",
    "permission": "owner",
    "avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
    "login": "john.doe@mycompany.com",
    "status": "accepting chats"
  },
  ...
]

Returns all LiveChat agents list. Optional parameters:

status - returns 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 a single agent details

Return complete details of the agent for the given LOGIN.

Path

GET https://api.livechatinc.com/agents/<LOGIN>

Example request

curl "https://api.livechatinc.com/agents/john.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

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

Properties

Property	Description
`login`	the agent's e-mail address
`name`	the agent's name
`login_status`	possible values: `accepting chats`, `not accepting chats`; defines the default status for agent right after login
`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`; current status of an agent
`last_logout`	timestamp of the agent's last logout
`api_key`	the agent's API key (note: agents can access their own API keys only)

Create a new agent

Path

POST https://api.livechatinc.com/agents

Example request

curl "https://api.livechatinc.com/agents" \
  -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&\"

Example JSON request

curl "https://api.livechatinc.com/agents" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "login":"jenny.doe@mycompany.com",
        "name":"Jenny Doe",
        "permission":"administrator",
        "groups":[1,2]
     }'

Example response

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

Creates a new agent in your license.

Required properties

Property	Description
`login`	must be correct e-mail address
`name`	string

Optional properties

Property	Description
`job_title`	defaults to: `Support Agent`
`login_status`	possible values: `accepting chats`, `not accepting chats`; defines the default status for agent right after login
`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 (required keys: `new_visitor`, `incoming_chat`, `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`

Update an agent

Path

PUT https://api.livechatinc.com/agents/<LOGIN>

Example request

curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT \
  -d "status=not+accepting+chats&\
max_chats_count=2"

Example JSON request

curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -X PUT \
  -d '{
        "status":"not accepting chats",
        "max_chats_count":2
     }'

Example response

{
  "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,
  "api_key": "441e519f755db8a51a4e232a31fe6249",
}

Updates the specified agent by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Optional properties

Property	Description
`job_title`
`name`
`login_status`	possible values: `accepting chats`, `not accepting chats`; defines the default status for agent right after login
`password`	the password you want to change
`current_password`	when changing the password for yourself or for another agent, you need to provide your current password
`permission`	`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`, allowed values: `0` or `1`)
`daily_summary`	`0` or `1`
`max_chats_count`
`work_scheduler`	available only for enterprise plan

Properties agent can edit on his own profile, without being an administrator:

password
name
job_title
daily_summary
notifications
login_status
status

Reset an API key

Reset API key for the agent with given LOGIN.

Path

POST https://api.livechatinc.com/agents/<LOGIN>/reset_api_key

Example request

curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com/reset_api_key" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X POST

Example response

Return format is the same as in update an agent method.

Remove an agent

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.

Path

DELETE https://api.livechatinc.com/agents/<LOGIN>

Example request

curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
  "result": "jenny.doe@mycompany.com removed successfully"
}

Methods	Path
`GET`	`/chats`
`GET`	`/chats/<CHAT_ID>`
`POST`	`/chats/<CHAT_ID>/send_transcript`
`PUT`	`/chats/<CHAT_ID>/tags`

Parameter	Description
`date_from`	`YYYY-MM-DD` Defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD` Defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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 id
`goal`	return chats for given goal id
`has_goal`	`1/0`. If 1 is passed, returns chats having any goal
`queued`	`1/0`. If 1 is passed, returns chats started from queue
`rate`	filter chats considering its rating status. Available values: `rated`, `not_rated`, `rated_good`, `rated_bad`
`include_pending`	`1/0`. Whether to include chats that haven't yet ended. Pending chats can be recognized by `pending: true` attribute
`tag[]`	filter chats by a specified tag
`tagged`	`1/0`. If 1 is passed, chats with any tag are returned. If 0 is passed, only chats without a tag are returned
`comment`	`1/0`. If 1 is passed, chats with rating comments are returned
`city`	filters by city, values should be entered and are returned in the local language
`region`	filters by region. This could be a state, voivodeship, canton, county etc. Values should be entered and are returned in the local language
`country`	filters by country name. All values are in english

Parameter	Description
`goal`	parameter will appear only if a goal for a particular chat has been reached
`referrer`	parameter will appear only if referrer url exists
`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
`queue`	parameter will appear only if chat started from queue
`engagement`	– possible values: `auto_invite` (chat from automatic invitation), `manual_invite` (chat from manual invitation), `immediate_start` (visitor started chats themselves)
`duration`	is counted in seconds
`total`	tells you the total number of chats
`pages`	tells you the total number of pages
`city`, `region`, `country`	geolocation filters have been working for chats since May 11, 2015

Parameter	Description
`to`	receiver's email address.

Visitor’s chat

This method allows you to perform a chat via your LiveChat as a visitor.

You can use this to create your own chat widget and, for example, place it within your mobile application.

When it comes to mobile widgets, you can use ready-made ones for iOS and Android.

Available paths

Methods	Path
`POST`	`/visitors/<VISITOR_ID>/chat/start`
`GET`	`/visitors/<VISITOR_ID>/chat/get_pending_messages`
`POST`	`/visitors/<VISITOR_ID>/chat/send_message`
`POST`	`/visitors/<VISITOR_ID>/chat/close`

Start chat

Path

POST /visitors/<VISITOR_ID>/chat/start

Example request

curl "https://api.livechatinc.com/visitors/5863759023/chat/start" \
-H X-API-Version:2 \
-d "licence_id=123&\
welcome_message=Hi"

Example response

{
  "secured_session_id":"CS1432649054.444adb0d90",
  "banned":false
}

This function creates new chat for a visitor and returns unique session ID, which is required to send, receive or close a given chat.

Required properties

Property	Description
`visitor_id`	unique ID of the visitor. It should be generated randomly on your side. If you already have an ID of your user in your database, it can be used as the `visitor_id`
`licence_id`	your LiveChat account number. You can obtain it from your LiveChat's installation code (the `__lc.license` param value)
`welcome_message`	short welcome message displayed at the beginning of the chat. Its maximum length is 1024 characters

Optional properties

Property	Description
`name`	visitor's name (defaults to "Client")
`email`	visitor's email address
`group`	group number (read more...)

Get pending messages

Path

GET https://api.livechatinc.com/visitors/<VISITOR_ID>/chat/get_pending_messages

Example request

curl "https://api.livechatinc.com/visitors/5863759023/chat/get_pending_messages?\
licence_id=123&\
secured_session_id=26132406c42c96ba61ed42689b70f719" \
-H X-API-Version:2

Example response

{
  "events":[
    {
      "agent":{
        "avatar":"livechat.s3.amazonaws.com/default/avatars/female_6.jpg",
        "job_title":"Support Agent",
        "name":"agent4"
      },
      "message_id":1,
      "timestamp":1432902625,
      "type":"agent_details",
      "user_type":"agent"
    },
    {
      "message_id":3,
      "text":"Hi, I need some help with entering my discount code.",
      "timestamp":1432902626,
      "type":"message",
      "user_type":"visitor"
    },
    { 
      "..." : "..."
    }
  ]
}

Returns messages and events in a pending chat.

Required properties

Property	Description
`licence_id`	your LiveChat account number. You can obtain it from your LiveChat's installation code (the `__lc.license` param value)
`secured_session_id`	secret session ID received from the `start` method

Optional properties

Property	Description
`last_message_id`	the ID of the last received message. You don't have to request the entire chat every time. You can simply start from a particular message ID

Send message

Path

POST https://api.livechatinc.com/visitors/<VISITOR_ID>/chat/send_message

Example request

curl "https://api.livechatinc.com/visitors/5863759023/chat/send_message" \
-H X-API-Version:2 \
-d "licence_id=123&\
secured_session_id=26132406c42c96ba61ed42689b70f719&\
message=Hello!"

Example response

{
  "success": true
}

Sends a new message as the visitor.

Required properties

Property	Description
`licence_id`	your LiveChat account number. You can obtain it from your LiveChat's installation code (the `__lc.license` param value)
`secured_session_id`	secret session ID received from the `start` method
`message`	the contents of the message

Close chat

Path

POST https://api.livechatinc.com/visitors/<VISITOR_ID>/chat/close

Example request

curl "https://api.livechatinc.com/visitors/5863759023/chat/close" \
-H X-API-Version:2 \
-d "licence_id=123&\
secured_session_id=26132406c42c96ba61ed42689b70f719&"

Example response

{
  "success": true
}

Ends the chat as a visitor.

Required properties

Property	Description
`licence_id`	your LiveChat account number. You can obtain it from your LiveChat's installation code (the `__lc.license` param value)
`secured_session_id` – secret session ID received from the `start` method

Canned responses

Use this method to get a full list of your Canned responses and to modify it.

Available paths

Methods	Path
`GET`, `POST`	`/canned_responses`
`GET`, `PUT`, `POST`	`/canned_responses/<CANNED_RESPONSE_ID>`

List all canned responses

Path

GET https://api.livechatinc.com/canned_responses

Example request

curl "https://api.livechatinc.com/canned_responses?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

[
  {
    "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"
    ]
  },
  {
      "...": "..."
  }
]

Returns list of all currently set canned responses.

Optional parameters

Parameter	Description
`group`	defaults to `0`
`modification_date`, `modification_by`	appear if the canned response was modified

Get single canned response

CANNED_RESPONSE_ID is obtained from the list all canned responses.

Path

GET https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>

Example request

curl "https://api.livechatinc.com/canned_responses/3151" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "id": 3151,
  "group": 1,
  "text": "Can I help you with anything else?",
  "creation_date": 1358257181,
  "created_by": "john.doe@mycompany.com",
  "tags": [
    "help",
    "else"
  ]
}

Attributes

Attribute	Description
`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

Create a new canned response

Path

POST https://api.livechatinc.com/canned_responses

Example request

curl "https://api.livechatinc.com/canned_responses" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "text=Have+a+great+day,+goodbye.&\
tags[]=bye&\
tags[]=cu"

Example JSON request

curl "https://api.livechatinc.com/canned_responses" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "text":"Have a great day, goodbye.",
        "tags": ["bye", "cu"]
     }'

Example response

{
  "id": 3181,
  "group": 0,
  "text": "Have a great day, goodbye.",
  "creation_date": 1358866421,
  "created_by": "john.doe@mycompany.com",
  "tags": [
    "cu",
    "bye"
  ]
}

Creates a new canned response.

Required properties

Property	Description
`text`	response text
`tags`	array of strings (tags)

Optional properties

Property	Description
`group`	defaults to 0

Update a canned response

Path

PUT https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>

Example request

curl "https://api.livechatinc.com/canned_responses/3181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "tags[]=bye"

Example JSON request

curl "https://api.livechatinc.com/canned_responses" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -X PUT \
  -d '{
        "tags": ["bye"]
     }'

Example response

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

Updates the specified canned response by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Optional properties

Property	Description
`text`	response text
`tags`	array of strings (tags)

Remove a canned response

Path

DELETE https://api.livechatinc.com/canned_responses/<CANNED_RESPONSE_ID>

Example request

curl "https://api.livechatinc.com/canned_responses/3181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
  "result": "Canned response removed successfully"
}

Removes a canned response with the given CANNED_RESPONSE_ID.

Goals

This method allows you to get information about your Goals and to modify them.

Available paths

Methods	Path
`GET`, `POST`	`/goals`
`GET`, `PUT`, `DELETE`	`/goals/<GOAL_ID>`
`POST`	`/goals/<GOAL_ID>/mark_as_successful`

List all goals

Path

GET https://api.livechatinc.com/goals

Example request

curl "https://api.livechatinc.com/goals" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

[
  {
    "id": 1041,
    "name": "purchase",
    "active": 1
  },
  {
    "id": 1181,
    "name": "nike shoes variable",
    "active": 1
  }
]

Returns all currently set goals. Parameter active tells you if the particular goal is enabled or not.

Get a single goal details

Path

GET https://api.livechatinc.com/goals/<GOAL_ID>

Example request

curl "https://api.livechatinc.com/goals/1181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "id": 1181,
  "name": "nike shoes variable",
  "active": 1,
  "type": "custom_variable",
  "custom_variable_name": "nike_shoes",
  "custom_variable_value": "true"
}

Returns goal details for the given GOAL_ID.

Attributes

Attribute	Description
`id`	id of the goal
`name`	goal name
`active`	whether or not the goal is enabled
`type`	type of the goal

Additional info

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

Mark goal as successful

Path

POST https://api.livechatinc.com/goals/<GOAL_ID>/mark_as_successful

Example request

curl "https://api.livechatinc.com/goals/1181/mark_as_successful" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "visitor_id=S1281361958.2238ee3bd3"

Example JSON request

curl "https://api.livechatinc.com/goals/1181/mark_as_successful" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "visitor_id":"S1281361958.2238ee3bd3",
     }'

Example response

{
  "result": "goal marked as successful"
}

GOAL_ID is obtained from the goals list.

Required parameters

Parameter	Description
`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.

Optional parameters

Parameter	Example
`order_id`	`AP723HVCA721`
`order_description`	`Nike shoes`
`order_price`	`199.00`, only the period is allowed as a separation character
`order_currency`	`USD`

Add a new goal

Path

POST https://api.livechatinc.com/goals

Example request

curl "https://api.livechatinc.com/goals" \
  -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"

Example JSON request

curl "https://api.livechatinc.com/goals" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
     }'

Example response

{
  "id": 2231,
  "name": "new goal",
  "active": 1,
  "type": "url",
  "match_type": "exact",
  "url": "http://www.mystore.com/checkout/thank_you"
}

Creates new goal.

Required parameters

Parameter	Description
`name`
`type`

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

Update a goal

Path

PUT https://api.livechatinc.com/goals/<GOAL_ID>

Example request

curl "https://api.livechatinc.com/goals/2231" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "name=new%20goal%20paused&\
  active=0"

Example JSON request

curl "https://api.livechatinc.com/goals/2231" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"new goal paused",
        "active":0
     }'

Example response

{
  "id": 2231,
  "name": "new goal paused",
  "active": 0,
  "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.

Optional parameters

Parameter	Description
`name`
`type`

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

Remove a goal

Path

DELETE https://api.livechatinc.com/goals/<GOAL_ID>

Example request

curl "https://api.livechatinc.com/goals/2231" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
  "result": "goal removed successfully"
}

Removes a goal with the given GOAL_ID.

Greetings

You can use this method to create new and modify existing Greetings. It can be also used to look up Greetings data.

Available paths

Methods	Path
`GET`, `POST`	`/greetings`
`GET`, `POST`, `DELETE`	`/greetings/<GREETING_ID>`

List all greetings

Path

GET -H X-API-Version:2 https://api.livechatinc.com/greetings

Example request

curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

[
  {
    "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!"
    }
  }
]

Returns the list of all greetings.

Optional properties

Property	Description
`group`	Group number can be specified to get greetings from a given group. If not specified, all greetings will be returned

Get a single greeting

Path

GET -H X-API-Version:2 https://api.livechatinc.com/greetings/<GREETING_ID>

Example request

curl "https://api.livechatinc.com/greetings/2411" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example result

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

Returns the specified greeting.

Additional info:

active – Tells you whether the greeting is enabled or not
rules – Gives you an array with all the rules for the specified greeting.

Create a new greeting

Path

[POST] /greetings

Use this function to create a new greeting.

Required properties

Property	Description
`name`	greeting name displayed in LiveChat settings (not visible to your website visitors)
`rules`	an array of conditions that must be met for the greeting to be displayed. Greeting rules are documented below

Optional properties

Property	Description
`group`	creates a greeting displayed in particular group only. Defaults to `0`

Greeting rules

Example request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "name=my+custom+invitation&\
rules[0][type]=visit_time_page&\
rules[0][value]=15&\
rules[0][operator]=greater_than&\
rules[1][type]=visits_number&\
rules[1][value]=2&\
rules[1][operator]=greater_or_equal"

Example JSON request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
          }
        ]
      }'

Example result

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

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 greeting rules you can use:

Rule	Description
`visit_time_site`	After visitor spent a certain amount of time on site
`visit_time_page`	After visitor spent a certain amount of time on page
`url_current`	For visitors on specific pages
`url_visited`	When visitor visited specific pages
`pages_view_number`	For visitors who have seen the page for a number of times
`url_referrer`	When the visitor arrived from a referring page
`geolocation`	For visitors from specific countries or cities
`visits_number`	For returning visitors
`search_keyword`	When visitor looked up a search keyword
`custom_variable`	The greeting will be sent when the specified variable is met documented below
`url_funnel`	Visitors who visit the specified sequence of websites will receive the greeting documented below

Custom variable

Example request

curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "name=custom+variable+type+greeting&\
rules[0][type]=custom_variable&\
rules[0][variable_name]=my_custom_var&\
rules[0][variable_value]=var_value&\
rules[0][operator]=contains"

Example JSON request

curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
          }
        ]
      }'

Example result

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

The greeting will be sent when the specified variable is met.

URL Funnel

Example request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "name=url+funnel+type+greeting&\
rules[0][type]=url_funnel&\
rules[0][urls][0][url]=mystore.com/shoes&\
rules[0][urls][0][operator]=equals&\
rules[0][urls][1][url]=cart&\
rules[0][urls][1][operator]=contains"

Example JSON request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
              }
            ]
          }
        ]
      }'

Example result

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

Visitors who visit the specified sequence of websites will receive the greeting.

Greetings with mutliple rules

Example request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "name=my+custom+invitation&\
rules[0][type]=visit_time_site&\
rules[0][value]=15&\
rules[1][type]=custom_variable&\
rules[1][variable_name]=empty_cart&\
rules[1][variable_value]=true&\
rules[2][type]=url_current&\
rules[2][value]=shoes&\
rules[2][operator]=contains"

Example JSON request

curl "https://api.livechatinc.com/greetings" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
          }
        ]
      }'

Example result

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

You can create a greeting that will have more than one rule.

Update a greeting

Path

PUT -H X-API-Version:2 -d "..." "https://api.livechatinc.com/greetings/<GREETING_ID>"

You can change the previously created greetings using this request. GREETING_ID is obtained from the all greetings list.

Update greeting name or message

Example request

curl "https://api.livechatinc.com/greetings/2491" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "name=athletic+shoes&\
properties[greeting-message_text]=Hello"

Use this request to change the name or message of a greeting.

Activate and deactivate greetings

Example request

curl "https://api.livechatinc.com/greetings/2491" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "active=0"

Activate or deactivate a greeting using this request.

Change greetings rules

Example request

curl "https://api.livechatinc.com/greetings/2491"\
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "rules[0][type]=custom_variable&\
rules[0][variable_name]=athletic_shoes&\
rules[0][variable_value]=true"

Example result

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

Change the rules of your greetings with this request.

Remove a greeting

Path

DELETE https://api.livechatinc.com/greetings/<GREETING_ID>

Example request

curl "https://api.livechatinc.com/greetings/2491" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
  "ok": true
}

Removes an greeting.

Groups

Use this method to get Agent Groups data and also to create new and modify existing Groups.

Available paths

Methods	Path
`GET`, `POST`	`/groups`
`GET`, `PUT`, `DELETE`	`/groups/<GROUP_ID>`

List all groups

Path

GET https://api.livechatinc.com/groups

Example request

curl "https://api.livechatinc.com/groups" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

[
  {
    "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 all created groups.

Additional info:

language tells you the chat window language for the particular group.
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 a single group details

Path

GET https://api.livechatinc.com/groups/<GROUP_ID>

Example request

curl "https://api.livechatinc.com/groups/2" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "id": 2,
  "name": "Sales",
  "language": "en",
  "agents": [
    "john.doe@mycompany.com",
    "jenny.doe@mycompany.com"
  ],
  "status": "accepting chats"
}

Returns group details for the given GROUP_ID.

Attributes

Attribute	Description
`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.

Create a new group

Path

POST https://api.livechatinc.com/groups

Example request

curl "https://api.livechatinc.com/groups" \
  -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"

Example JSON request

curl "https://api.livechatinc.com/groups" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
       "name":"Human Resources",
       "agents[0]":"jenny.doe@mycompany.com",
       "agents[1]":"john.doe@mycompany.com" 
      }'

Example response

{
  "id": 4,
  "name": "Human Resources",
  "language": "en",
  "agents": [
    "jenny.doe@mycompany.com",
    "john.doe@mycompany.com"
  ],
  "status": "offline"
}

Creates a new group in your license.

Required properties

Property	Description
`name`	group name
`agents`	an array of LiveChat users' logins (e-mails)

Optional properties

Property	Description
`language`	group language (defaults to English). See the list of supported languages

Update a group

Path

PUT https://api.livechatinc.com/groups/<GROUP_ID>

Example request

curl "https://api.livechatinc.com/groups/3" \
  -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"

Example JSON request

curl "https://api.livechatinc.com/groups/3" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 -X PUT \   
  -H Content-type:application/json \
  -d '{
        "name"="Quality Assurance",
        "agents[0]":"john.doe@mycompany.com",
        "agents[1]":"jane.doe@mycompany.com"
      }'

Example response

{
  "id": 3,
  "name": "Quality Assurance",
  "language": "en",
  "agents": [
    "john.doe@mycompany.com",
    "jane.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

Property	Description
`name`	group name
`language`	see the list of supported languages
`agents`	an array of LiveChat users' logins (e-mails)

Remove a group

Path

DELETE https://api.livechatinc.com/groups/<GROUP_ID>

Example request

curl "https://api.livechatinc.com/groups/4" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
  "result": "group removed successfully"
}

Removes a group with the given GROUP_ID.

Reports

This method allows you to access and extract all the Reports data available in LiveChat.

Available paths

Methods	Path
`GET`	`/reports/chats/total_chats`
`GET`	`/reports/chats/engagement`
`GET`	`/reports/chats/ratings`
`GET`	`/reports/chats/ratings/ranking`
`GET`	`/reports/chats/queued_visitors`
`GET`	`/reports/chats/queued_visitors/waiting_times`
`GET`	`/reports/availability`
`GET`	`/reports/chats/chatting_time`
`GET`	`/reports/chats/first_response_time`
`GET`	`/reports/chats/response_time`
`GET`	`/reports/chats/goals`
`GET`	`/reports/chats/greetings`
`GET`	`/reports/tickets/new_tickets`
`GET`	`/reports/tickets/first_response_time`
`GET`	`/reports/tickets/solved_tickets`
`GET`	`/reports/tickets/resolution_time`
`GET`	`/reports/tickets/ticket_sources`
`GET`	`/reports/tickets/ratings`
`GET`	`/reports/tickets/ratings/ranking`

Total chats

Path

GET https://api.livechatinc.com/reports/chats/total_chats

Example request

curl "https://api.livechatinc.com/reports/chats/total_chats?\
date_from=2013-01-29&\
date_to=2013-01-29&\
agent=john.doe@mycompany.com&\
group_by=hour" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "00:00": {
    "chats": 18
  },
  "01:00": {
    "chats": 19
  },
    "02:00": {
    "chats": 6
  },
    "03:00": {
      "chats": 15
  },
  "04:00": {
    "chats": 10
  },
  "05:00": {
    "chats": 14
  },
  "06:00": {
    "chats": 11
  },
  //(...)
  "21:00": {
    "chats": 0
  },
  "22:00": {
    "chats": 0
  },
  "23:00": {
    "chats": 2
  }
}

Shows how many chats occurred during the specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Chat engagement

Path

GET https://api.livechatinc.com/reports/chats/engagement

Example request

curl "https://api.livechatinc.com/reports/chats/engagement?\
date_from=2013-01-28&\
date_to=2013-01-29&\
agent=john.doe@mycompany.com&\
tag[]=sales&\
group_by=hour" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2013-01-28":{
    "chats_from_auto_invite":1,
    "chats_from_immediate_start":0,
    "chats_from_manual_invite":3
  },
  "2013-01-29":{
    "chats_from_auto_invite":0,
    "chats_from_immediate_start":2,
    "chats_from_manual_invite":0
  }
}

This report shows you where do you get your chats, i.e. from automatic invitations, manual invitations or visitors starting chats themselves.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Chat ratings report

Path

GET https://api.livechatinc.com/reports/chats/ratings

Example request

curl "https://api.livechatinc.com/reports/chats/ratings?\
group=2&\
date_from=2012-01-29&\
date_to=2013-01-29&\
group_by=month" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

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

Shows how many chats were rated and how they have been rated during specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Chat Ranking

Path

GET https://api.livechatinc.com/reports/chats/ratings/ranking

Example request

curl "https://api.livechatinc.com/reports/chats/ratings/ranking" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "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 the ratio of good to bad ratings for each operator.

Optional arguments

Argument	Description
`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
`tag`	return statistics for the specified tag

Queued visitors

Path

GET https://api.livechatinc.com/reports/chats/queued_visitors

Example request

curl "https://api.livechatinc.com/reports/chats/queued_visitors?\
date_from=2013-01-29&\
group=2" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "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 how many visitors were waiting in the queue, how many abandoned the queue or proceeded to chats.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`

Queue waiting times

Path

GET https://api.livechatinc.com/reports/chats/queued_visitors/waiting_times

Example request

curl "https://api.livechatinc.com/reports/chats/queued_visitors/waiting_times?\
date_from=2013-01-29&\
group=2" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2013-01-29":{
    "queued":{
      "count": 1,
      "min":{
        "seconds":0
      },
      "max":{
        "seconds":112
      },
      "average":{
        "seconds":24
      }
    },
    "left_queue":{
      "count": 3,
      "min":{
        "seconds":33
      },
      "max":{
        "seconds":56
      },
      "average":{
        "seconds":44
      }
    },
    "entered_chat":{
      "count": 2,
      "min":{
        "seconds":10
      },
      "max":{
        "seconds":112
      },
      "average":{
        "seconds":23
      }
    }
  }
}

Shows Minimum, Average and Maximum waiting time.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`

Availability

Path

GET https://api.livechatinc.com/reports/availability

Example request

curl "https://api.livechatinc.com/reports/availability?\
date_from=2013-01-25&\
date_to=2013-01-30&\
agent=john.doe@mycompany.com&\
group_by=day"\
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

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

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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

Chatting time

Path

GET https://api.livechatinc.com/reports/chats/chatting_time

Example request

curl "https://api.livechatinc.com/reports/chats/chatting_time?\
date_from=2013-01-25&\
date_to=2013-01-30&\
group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

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

Argument	Description
`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 agent
`tag`	return statistics for the specified tag

Chats first response time

Path

GET https://api.livechatinc.com/reports/chats/first_response_time

Example request

curl "https://api.livechatinc.com/reports/chats/first_response_time?\
date_from=2014-01-10&\
date_to=2014-01-20&\
agent=john.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "first_response_time": {
      "count": 5,
      "seconds": 0.83
    }
  },
  "2014-01-11": {
    "first_response_time": {
      "count": 1,
      "seconds": 1.3
    }
  },
  //(...)
  "2014-01-20": {
    "first_response_time":{
      "count": 0,
      "seconds": null
    }
  }
}

The average amount of time it takes for agents to respond to a new chat over a specified period of time.

Optional arguments

Argument	Description
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

The following parameters are returned for each date:

count – the number of chat first responses during the specified period.
seconds – average first response time.

Chats response time

Path

GET https://api.livechatinc.com/reports/chats/response_time

Example request

curl "https://api.livechatinc.com/reports/chats/response_time?\
date_from=2014-01-10&\
date_to=2014-01-20&\
agent=john.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "avg_response_time": {
      "count": 5,
      "seconds": 0.83
    }
  },
  "2014-01-11": {
    "avg_response_time": {
      "count": 1,
      "seconds": 1.3
    }
  },
  //(...)
  "2014-01-20": {
    "avg_response_time":{
      "count": 0,
      "seconds": null
    }
  }
}

The average amount of time it takes for agents to respond to a new message in a chat during a specified period.

Optional arguments

Argument	Description
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

The following parameters are returned for each date:

count – the number of chat responses during the specified period.
seconds – average response time.

Number of simultaneous chats

Path

GET https://api.livechatinc.com/reports/chats/agents_occupancy

Example request

curl "https://api.livechatinc.com/reports/chats/agents_occupancy?\
weekday=mon" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
    "2015-03-16 00:00": 0,
    "2015-03-16 01:00": 0,
    "2015-03-16 02:00": 0,
    "2015-03-16 03:00": 0,
    "2015-03-16 04:00": 0,
    "2015-03-16 05:00": 0,
    "2015-03-16 06:00": 0,
    "2015-03-16 07:00": 0,
    "2015-03-16 08:00": 0,
    "2015-03-16 09:00": 13,
    "2015-03-16 10:00": 17,
    "2015-03-16 11:00": 20,
    "2015-03-16 12:00": 20,
    "2015-03-16 13:00": 16,
    "2015-03-16 14:00": 16,
    "...": "...",
    "2015-03-23 00:00": 0,
    "2015-03-23 01:00": 0,
    "2015-03-23 02:00": 0,
    "2015-03-23 03:00": 0,
    "2015-03-23 04:00": 0,
    ...
    "2015-04-06 23:00": 0
}

This request shows the maximum number of concurrent chats that have happened at the same hour on a particular day.

Required arguments

Argument	Description
`weekday`	you can select the day by changing the weekday parameter to one of the following values: `mon` for Monday, `tue` for Tuesday, `wed` for Wednesday, `thu` for Thursday, `fri` for Friday, `sat` for saturday and `sun` for Sunday

Goals

Path

GET https://api.livechatinc.com/reports/chats/goals

Example request

curl "https://api.livechatinc.com/reports/chats/goals?\
date_from=2013-01-01&\
goal=71&group_by=month" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2013-01": {
    "begin": "2013-01-01",
    "end": "2013-01-30",
    "goals": 4
  }
}

Shows the number of reached goals.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`group`	id of the group, not set by default, returns statistics for the specified group
`goal`	id of the goal, not set by default
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Greetings

Path

GET https://api.livechatinc.com/reports/chats/greetings

Example request

curl "https://api.livechatinc.com/reports/chats/greetings?\
date_from=2014-01-13&\
date_to=2014-02-14&\
group_by=month" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01": {
    "begin": "2014-01-13",
    "end": "2014-01-31",
    "displayed": 274,
    "accepted": 190,
    "goals": 40
  },
  "2014-02": {
  "begin": "2014-02-01",
    "end": "2014-02-14",
    "displayed": 146,
    "accepted": 88,
    "goals": 22
  }
}

Returns the “greetings to chats to goals” conversion rates report.

displayed is the number of displayed greetings. accepted tells you how many chats resulted from these greetings. goals tells you how many goals resulted from these greetings.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`group`	id of the group, not set by default, returns statistics for the specified group
`goal`	id of the goal, not set by default
`greeting`	`id` of the greeting, not set by default, returns statistics for the specified greeting
`group_by`	defaults to `day` (or `hour` when date_from equals date_to), can be set to `month`, `hour` or `day`
`tag`	return statistics for the specified tag

New tickets

Path

GET https://api.livechatinc.com/reports/tickets/new_tickets

Example request

curl "https://api.livechatinc.com/reports/tickets/new_tickets?\
date_from=2013-01-29&\
date_to=2013-01-29&\
group_by=hour" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "00:00": {
    "new_tickets": 5
  },
  "01:00": {
    "new_tickets": 1
  },
  //(...)
  "23:00": {
    "new_tickets": 21
  }
}

Shows the number of the tickets created during the specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Tickets first response time

Path

GET https://api.livechatinc.com/reports/tickets/first_response_time

Example request

curl "https://api.livechatinc.com/reports/tickets/first_response_time?\
date_from=2014-01-10&\
date_to=2014-01-20&\
agent=john.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "count": 5,
    "hours": 0.83
  },
  "2014-01-11": {
    "count": 1,
    "hours": 1.3
  },
  //(...)
  "2014-01-20": {
    "count": 0,
    "hours": null
  }
}

Shows the time of the first response to tickets that were responded to for the first time during the specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`agent`	agent's login, not set by default, return statistics for the specified agent
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

The following parameters are returned for each date:

count – the number of tickets that were responded to for the first time that day.
hours – average first response time of the tickets. For example, "hours": 0.83 means an average first response time of 49mins 48sec.

Solved tickets

Path

GET https://api.livechatinc.com/reports/tickets/solved_tickets

Example request

curl "https://api.livechatinc.com/reports/tickets/solved_tickets?\
date_from=2014-01-10&\
date_to=2014-01-20" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "solved_tickets": 4
  },
  "2014-01-11": {
    "solved_tickets": 12
  },
  //(...)
  "2014-01-20": {
    "solved_tickets": 4
  }
}

Shows the number of the tickets solved during the specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`agent`	agent's login, not set by default, return statistics for the specified agent
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Tickets resolution time

Path

GET https://api.livechatinc.com/reports/tickets/resolution_time

Example request

curl "https://api.livechatinc.com/reports/tickets/resolution_time?\
date_from=2014-01-10&\
date_to=2014-01-20" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "count": 3,
    "hours": 16.27
  },
  "2014-01-11": {
    "count": 0,
    "hours": null
  },
  //(...)
  "2014-01-20": {
    "count": 2,
    "hours": 1.8
  }
}

Shows the resolution time of the tickets that were solved during the specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`agent`	agent's login, not set by default, return statistics for the specified agent
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Two parameters are returned:

count – the number of tickets that were responded to for the first time that day.
hours – average first response time of the tickets. For example, "hours": 0.83 means an average first response time of 49mins 48sec.

Ticket sources

Path

GET https://api.livechatinc.com/reports/tickets/ticket_sources

Example request

curl "https://api.livechatinc.com/reports/tickets/ticket_sources?\
date_from=2014-01-10&\
date_to=2014-01-20" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2014-01-10": {
    "tickets_from_chat_window": 4,
    "tickets_from_mail": 12,
    "tickets_from_chat": 2
  },
  "2014-01-11": {
    "tickets_from_chat_window": 7,
    "tickets_from_mail": 8,
    "tickets_from_chat": 6
  },
  //(...)
  "2014-01-20": {
    "tickets_from_chat_window": 0,
    "tickets_from_mail": 16,
    "tickets_from_chat": 1
  }
}

Shows the distribution of tickets between various channels.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

The following parameters are returned for each date:

tickets_from_chat_window – the number of tickets created by the visitor via the ticket form,
tickets_from_mail – the number of tickets created by sending an email to your support email tied to LiveChat,
tickets_from_chat – the number of tickets created by the agents during a chat.

Ticket ratings report

Path

GET https://api.livechatinc.com/reports/tickets/ratings

Example request

curl "https://api.livechatinc.com/reports/tickets/ratings?\
group=2&\
date_from=2012-01-29&\
date_to=2013-01-29&\
group_by=month" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "2012-01": {
    "begin": "2012-01-29",
    "end": "2012-01-31",
    "bad": 0,
    "good": 6
  },
  "2012-02": {
    "begin": "2012-02-01",
    "end": "2012-02-29",
    "bad": 4,
    "good": 38
  },
  "2012-03": {
    "begin": "2012-03-01",
    "end": "2012-03-31",
    "bad": 0,
    "good": 16
  },
  //(...) 
  "2012-11": {
    "begin": "2012-11-01",
    "end": "2012-11-30",
    "bad": 20,
    "good": 49
  },
  "2012-12": {
    "begin": "2012-12-01",
    "end": "2012-12-31",
    "bad": 22,
    "good": 35
  },
  "2013-01": {
    "begin": "2013-01-01",
    "end": "2013-01-29",
    "bad": 18,
    "good": 51
  }
}

Shows tickets have been rated during specified period.

Optional arguments

Argument	Description
`date_from`	`YYYY-MM-DD`, defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`, defaults to `today`
`timezone`	timezone in the TZ format (e.g. America/Phoenix)
`agent`	agent's login, not set by default, return statistics for the specified agent
`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`, `hour` or `day`
`tag`	return statistics for the specified tag

Ticket Ranking

Path

GET https://api.livechatinc.com/reports/tickets/ratings/ranking

Example request

curl "https://api.livechatinc.com/reports/tickets/ratings/ranking" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "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 the ratio of good to bad ratings for each operator.

Optional arguments

Argument	Description
`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
`tag`	return statistics for the specified tag

Status

You can use this method to check whether your LiveChat is online or offline.

Available paths

Methods	Path
`GET`	`/status`

Get status

Path

GET https://api.livechatinc.com/status

Example request

curl "https://api.livechatinc.com/status/1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "status":"online"
}

Returns current LiveChat status. Available return values: online, offline.

Optional parameters

Parameter	Description
`group`	defaults to 0

Tickets

Use this method to get information about a specific or all Ticket cases. You also use it to create new Tickets or update tags for existing Tickets.

Available paths

Methods	Path
`GET`	`/tickets/chats/total_chats`
`GET`	`/tickets/<TICKET_ID>`
`POST`	`/tickets`
`PUT`	`/tickets/<TICKET_ID>/tags`

Get list of tickets

Path

GET https://api.livechatinc.com/tickets

Example request

curl "https://api.livechatinc.com/tickets?\
date_from=2013-11-15&\
status=open" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

{
  "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"
  ],
  (...)
  ]
}

Returns all tickets.

Optional parameters

Parameter	Description
`date_from`	`YYYY-MM-DD`. Returns tickets with any of its activities matching the date. Defaults to `the beginning of time`
`date_to`	`YYYY-MM-DD`. Returns tickets with any of its activities matching the date. Defaults to `today`
`page`	page number, defaults to 1
`assigned`	if `0`, returns only unassigned tickets. If `1`, returns only tickets assigned to any agent
`order`	orders tickets by date of last ticket modification. Possible values: `desc`, `asc`. Defaults to `desc`
`status`	not set by default. Possible values: `open`, `pending`, `solved` or `spam`
`assignee`	return tickets assigned to given agent's login
`query`	return tickets containing the query
`requester[mail]`	return tickets assigned to given requester
`group`	return tickets for given group
`source`	return tickets for given source. Possible values: `lc2` (created from archives), `mail`, `facebook`, `agent-app-manual` (created manually), `chat-window` (created from ticket form)
`tag`	return statistics for the specified tag
`tagged`	`1/0`. If 1 is passed, returns tickets having any tag. If 0 passed, returns tickets without any tag

Additional info:

Results are divided into pages, each containing 25 tickets.

total tells you the total number of tickets.
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 single ticket

Path

GET https://api.livechatinc.com/tickets/<TICKET_ID>

Example request

curl "https://api.livechatinc.com/tickets/5FUED" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

Return format is the same as the single ticket item in tickets list.

Returns single ticket item for the given TICKET_ID.

Create a ticket

Path

POST https://api.livechatinc.com/tickets

Example request

curl "https://api.livechatinc.com/tickets" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2  \
  -X POST -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&\
  requester[name]=Mary+Brown"

Example JSON request

curl "https://api.livechatinc.com/tickets" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -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"
      }
     }'

Example response

Return format is the same as the single ticket item in [tickets list](#get-tickets).

Creates a new ticket.

Required parameters

Parameter	Description
`message`	requester's message
`requester[mail]`	requester's email address

Optional parameters

Parameter	Description
`requester[name]`	requester's name
`assignee[id]`	login of the agent that will be assigned to the ticket
`source[type]`	source of the ticket. Possible values: `chat-window`, `mail` or `lc2`. Defaults to `lc2`
`source[url]`	url of the website that the ticket was sent from. Applies only if `source[type]` is `chat-window`
`subject`	ticket subject. Defaults to `(no subject)`
`group`	list of groups. Must be an array with group IDs. Defaults to `[0]`

Update ticket tags

Path

PUT https://api.livechatinc.com/tickets/<TICKET_ID>/tags

Example request

curl "https://api.livechatinc.com/tickets/5FUED/tags" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT \
  -d "tag[]=sales&\
tag[]=support&\
tag[]=feedback"

Example JSON request

curl "https://api.livechatinc.com/tickets/5FUED/tags" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "tag":["sales","support","feedback"]
     }'

Example response

{
  "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"
  ],
  (...)
  ]
}

Updates tags associated with the ticket.

Required parameters

Parameter	Description
`tag`	array of used tags

Visitors

You can use this method to get information about real-time Visitors on your website. You can also use it to display additional information about the visitors in the LiveChat app.

Available paths

Methods	Path
`GET`	`/visitors`
`POST`	`/visitors/<VISITOR_ID>/details`

List all visitors

Path

GET https://api.livechatinc.com/visitors

Example request

curl "https://api.livechatinc.com/visitors?
state=chatting&\
group[]=0" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 -g

Example response

[
  {
    "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://docs.livechatinc.com/js-api/#on-chat-window-minimized",
    "page_current": "https://docs.livechatinc.com/js-api/#on-chat-window-minimized",
    "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.livechatinc.com/",
    "region": "North Carolina",
    "state": "chatting",
    "timezone": "America/New_York",
    "visit_path": [
      {
        "invitation": "Time on site: 30 sec",
        "page": "https://developers.livechatinc.com/",
        "time": "2017-02-16 12:36:21",
        "time_ref": 1487244981,
        "time_ts": 1487244981,
        "title": "LiveChat Developers - REST API & Integrations"
      },
      {
        "invitation": "",
        "page": "https://docs.livechatinc.com/",
        "time": "2017-02-16 12:38:33",
        "time_ref": 1487245113,
        "time_ts": 1487245113,
        "title": "LiveChat Docs"
      },
      // (...)
    ],
    "visits": 3
  },
  // (...)
]

Returns list of the visitors available on pages with tracking code installed.

Optional parameters

Parameter	Description
`state`	parameter determines what state the visitors are. Possible values: `chatting`, `queued`, `browsing`, `invited`, `refused invitation` or `chat closed`
`group[]`	parameter decides which group will be used for the listing. Use group numbers as values to select visitors only for the specified group
`count`	parameter 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:

Possible state values returned without any filter are:

browsing
chatting
logging into chat
queued
invited
refused invitation
chat closed

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.

Add custom visitor details

Path

POST https://api.livechatinc.com/visitors/<VISITOR_ID>/details

Example request

curl "https://api.livechatinc.com/visitors/S1352647457.ac951bfe2e/details" \
  -H X-API-Version:2
  -d "license_id=12345&\
token=26132406c42c96ba61ed42689b70f719&\
id=my-app&\
fields[0][name]=Age&\
fields[0][value]=36"

Example JSON request

curl "https://api.livechatinc.com/visitors/S1352647457.ac951bfe2e/details" \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d "{
        "license_id":12345,
        "token":"26132406c42c96ba61ed42689b70f719",
        "id":"my-app",
        "fields":[
          {
            "name":"Age",
            "value":36
          }
        ]
      }"

Example response

{
  "result": "Visitor details added"
}

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

Property	Description
`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. For the links you can also pass the anchor text. By adding `url` param, the value field would act as the anchor.

Optional properties

Property	Description
`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.

Webhooks

This method will help you build your own LiveChat integrations by creating and managing webhooks.

Check out out webhooks tutorial for more information and on how to get started and a few use-cases.

Available paths

Methods	Path
`GET`	`/webhooks`
`POST`	`/webhooks`
`DELETE`	`/webhooks/<WEBHOOK_ID>`

Display configured webhooks

Path

GET https://api.livechatinc.com/webhooks

Example request

curl "https://api.livechatinc.com/webhooks" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2

Example response

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

Returns list of webhooks that have been created in LiveChat account.

Create a new webhook

Path

POST https://api.livechatinc.com/webhooks

Example request

curl "https://api.livechatinc.com/webhooks" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
  -d "event_type=chat_started&\
data_types[]=chat&\
data_types[]=visitor&\
url=http://my-company.com/parse_webhook.php

Example response

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

Creates a new webhook.

Required properties

Property	Description
`event_type`	must be one of `chat_started`, `chat_ended`, `visitor_queued` or `ticket_created`
`data_types`	determines what information the webhook will contain
`url`	the URL address the webhook will be sent to

Additional info:

event_type determines when the webhook will be sent to your script:

Property	Description
`chat_started`	when the chat is started
`chat_ended`	when the chat is ended
`visior_queued`	when the visitor enters the queue before a chat
`ticket_created`	when a new ticket is created

data_type is an array that includes one or more of the following values):

Property	Description
`chat`	only supported in `chat_started` and `chat_ended` event types
`visitor`	only supported in `chat_started`, `chat_ended` and `visitor_queued` event types
`pre_chat_survey`	only supported in `chat_started` and `chat_ended` event types
`ticket`	only supported in `ticket_created` event type

Delete a webhook

Path

DELETE https://api.livechatinc.com/webhooks/<ID>

Example request

curl "https://api.livechatinc.com/webhooks/39612eee5(...)" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE

Example response

{
    "result":"Push notification removed successfully"
}

Deletes webhook with given ID.

Parameter	Description
`author`	agent login
`tag`	name of a tag
`group`	id of the group that tag will be added to

Introduction

Basic API usage

Authentication

Data format

JSONP

Error handling

HTTP status codes summary

Cross-domain

LiveChat API libraries

External LiveChat API libraries

Agents

Available paths

List all agents

Get a single agent details

Properties

Create a new agent

Required properties

Optional properties

Update an agent

Optional properties

Reset an API key

Remove an agent

Archives

Available paths

Get list of chats

Optional parameters

Additional info

Get single chat

Send chat transcript to e-mail

Required parameter

Update chat tags

Required parameter

Visitor’s chat

Available paths

Start chat

Required properties

Optional properties

Get pending messages

Required properties

Optional properties

Send message

Required properties

Close chat

Required properties

Canned responses

Available paths

List all canned responses

Optional parameters

Get single canned response

Attributes

Create a new canned response

Required properties

Optional properties

Update a canned response

Optional properties

Remove a canned response

Goals

Available paths

List all goals

Get a single goal details

Attributes

Additional info

Mark goal as successful

Required parameters

Optional parameters

Add a new goal

Required parameters

Additional info

Update a goal

Optional parameters

Additional info

Remove a goal

Greetings

Available paths

List all greetings

Optional properties

Get a single greeting

Additional info:

Create a new greeting

Required properties