MENU

Introduction

Welcome to the LiveChat API documentation!

Our API provides a set of flexible tools which you can use to create new outstanding projects. We smile a bit more each time we see skilled developers unleash their creativity!

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

Basic API usage

Sample method call

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

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

The next segment of the URI path depends on the type of your request. For example, use: https://api.livechatinc.com/agents to get or modify the agents data.

Authentication

Two common authentication methods are supported: OAuth 2.0 and API key.

OAuth 2.0

Example REST API call using OAuth 2.0 access_token:

  curl "https://api.livechatinc.com/agents" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "X-API-Version: 2"

OAuth 2.0 authentication is the recommended way of authenticating to LiveChat API.

It is the most secure way of making API calls. With this flow, you will get access only to some parts of LiveChat account, such as reading agents list. This is more secure than API key flow which has always access to all LiveChat account data.

To start using OAuth 2.0, please read a dedicated Authorization guide.

API key

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 this:

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

If you want to build a private app that will run on your own server, you can skip the OAuth 2.0 flow and use the API key. Please note this flow of making API calls is less secure because the API key gives access to all LiveChat account data.

With this authorization method, you will need to include your LiveChat login and API_KEY for each method call. You'll find the 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.

Data format

Sample agents list returned in the JSON format

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

The LiveChat API returns the data in the JSON format. Check out the following example.

JSONP

Sample JSONP request

curl -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb "https://api.livechatinc.com/agents?callback=example"

All requests made with HTTP GET are JSONP-enabled. To use JSONP, append callback= and the name of your callback function to the request.

Sample JSONP response

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

Error handling

The errors are returned using the standard HTTP error code syntax. In general, the codes in the 2xx range indicate success, the codes in the 4xx range indicate an error (incorrect or missing parameters, not authenticated etc.), and the codes in the 5xx range indicate an error with the LiveChat servers. Any additional info is included in the body of the return call, JSON-formatted.

HTTP status codes summary

Cross-domain

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

LiveChat API libraries

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

External LiveChat API libraries

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

Sample request

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

Sample 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:

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

Returns complete details of the agent for the given LOGIN.

Path

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

Sample request

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

Sample 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 an agent right after the login
permission possible values: owner, administrator, normal
daily_summary whether or not the agent receives a 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

Sample 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&\"

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

Sample 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 a 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 an agent right after the 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, accepted 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>

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

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

Sample 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

The properties which an agent can edit in their own profile, without being an administrator:

Reset an API key

Resets the API key for an agent with a given LOGIN.

Path

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

Sample 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

Sample response

The return format is the same as in the update an agent method.

Remove an agent

Removes an agent. Archived chats will not be removed, but all statistics will be lost. The agent will be notified by e-mail that the account has been deleted.

Path

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

Sample request

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

Sample response

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

Archives

This method allows you to look up the past chats and after-hours messages. It also allows you to send chat transcripts via email.

Available paths

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

Get list of chats

Path

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

Sample request

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

Sample response

{
   "chats":[
      {
         "type":"chat",
         "id":"MH022RD0K5",
         "visitor":{
            "id":"S1355415390.49b8940793",
            "name":"Mary Brown",
            "ip":"85.10.5.156",
            "city": "Central District",
            "country": "Hong Kong",
            "country_code": "HK",
            "timezone": "Asia/Hong_Kong",
            "region": ""
         },
         "agents":[
            {
               "display_name":"John Doe",
               "email":"john.doe@mycompany.com"
            }
         ],
         "supervisors":[
            {
               "display_name":"Jane Doe",
               "email":"jane.doe@mycompany.com"
            }
         ],
         "rate":"not_rated",
         "duration":1456,
         "chat_start_url":"https://livechatinc.com",
         "referrer":"https://domain.com",
         "group":[
            0
         ],
         "started":"Wed, 01/23/13 11:40:53 am",
         "prechat_survey":[
            {
               "key":"Name:",
               "value":"",
               "id":"13589376348060238"
            },
            {
               "key":"E-mail:",
               "value":"",
               "id":"135893763480606511"
            }
         ],
         "postchat_survey":[
            {
               "key":"How would you rate the quality of support?",
               "value":"Good",
               "id":"137164167769201638"
            }
         ],
         "custom_variables":[
            {
               "key":"customer_login",
               "value":"mary_brown"
            }
         ],
         "integration_variables":[
            {
               "key":"facebook.id",
               "value":"123456789"
            },
            // ...
            {
               "key":"facebook.email",
               "value":"mary.brown@email.com"
            }
         ],
         "goals":[
            {
               "id":71,
               "name":"goal_name",
               "order":{
                  "id":"ABC",
                  "description":"product one",
                  "price":"199",
                  "currency":"CZK"
               }
            },
            {
               "id":72,
               "name":"goal_name",
               "order":{

               }
            }
         ],
         "queue":{
            "duration":20
         },
         "tags":[
            "sales",
            "support",
            "feedback"
         ],
         "timezone": "Europe/Berlin",
         "messages":[
            {
               "author_name":"John Doe",
               "text":"Hello",
               "date":"Wed, 01/23/13 11:40:53 am",
               "timestamp":1358937653,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com"
            },
            // ...
         ],
         "events":[
            {
               "author_name":"John Doe",
               "text":"Hello",
               "date":"Wed, 01/23/13 11:40:53 am",
               "timestamp":1358937653,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com",
               "type":"message"
            },
            {
               "text":"Mary Brown uploaded the attachment.",
               "date":"Wed, 01/23/13 11:41:02 am",
               "timestamp":1358937662,
               "type":"attachment",
               "user_type":"visitor",
               "files":[
                  "https://static.livechatinc.com/.../hello.JPG"
               ],
               "author_name":"Mary Brown"
            },
            {
               "author_name":"John Doe",
               "text":"Thanks, fine :)",
               "date":"Wed, 01/23/13 11:41:05 am",
               "timestamp":1358937665,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com",
               "type":"message"
            },
            {
               "author_name":"Jane Doe",
               "text":"Message from supervisor.",
               "date":"Wed, 01/23/13 11:57:13 am",
               "timestamp":1358938633,
               "user_type":"supervisor",
               "agent_id":"jane.doe@mycompany.com",
               "type":"message"
            },
            {
               "text":"Mary Brown closed the chat.",
               "date":"Wed, 01/23/13 11:57:14 am",
               "timestamp":1358937663,
               "type":"event",
               "user_type":"visitor"
            },
         ],
         "engagement":immediate_start,
         "started_timestamp":1358937653,
         "ended_timestamp":1358939109,
         "ended":"Wed, 01/23/13 12:05:09 pm"
      },
      {
         "...":"..."
      }
   ],
   "total":2,
   "pages":1
}

Returns all ended chats.

Optional parameters

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

Additional info

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

The results are divided into pages, each containing 25 chats. To access next pages of the results, use ?page=<PAGE> parameter. Please note that first page's number is 1, not 0.

Get single chat

Returns a single chat item for the given CHAT_ID.

Path

GET https://api.livechatinc.com/chats/<CHAT_ID>

Sample request

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

Sample response

The return format is the same as the single chat item in get list of chats.

Send chat transcript to e-mail

Path

POST https://api.livechatinc.com/chats/<CHAT_ID>/send_transcript

Sample request

curl "https://api.livechatinc.com/chats/MH022RD0K5/send_transcript" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "to=john.doe@mycompany.com"

Sample JSON request

curl "https://api.livechatinc.com/chats/MH022RD0K5/send_transcript" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \  
  -d '{
       "to":"john.doe@mycompany.com"
      }'

Sample response

{
  "result": "E-mail has been sent to john.doe@mycompany.com."
}

Required parameter

Parameter Description
to receiver's email address.

Update chat tags

Path

PUT https://api.livechatinc.com/chats/<CHAT_ID>/tags

Sample request

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

Sample JSON request

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

Sample response

{
   "chats":[
      {
         "type":"chat",
         "id":"MH022RD0K5",
         "visitor":{
            "id":"S1355415390.49b8940793",
            "name":"Mary Brown",
            "ip":"85.10.5.156",
            "city": "Central District",
            "country": "Hong Kong",
            "country_code": "HK",
            "timezone": "Asia/Hong_Kong",
            "region": ""
         },
         "agents":[
            {
               "display_name":"John Doe",
               "email":"john.doe@mycompany.com"
            }
         ],
         "supervisors":[
            {
               "display_name":"Jane Doe",
               "email":"jane.doe@mycompany.com"
            }
         ],
         "rate":"not_rated",
         "duration":1456,
         "chat_start_url":"https://livechatinc.com",
         "referrer":"https://domain.com",
         "group":[
            0
         ],
         "started":"Wed, 01/23/13 11:40:53 am",
         "prechat_survey":[
            {
               "key":"Name:",
               "value":"",
               "id":"13589376348060238"
            },
            {
               "key":"E-mail:",
               "value":"",
               "id":"135893763480606511"
            }
         ],
         "postchat_survey":[
            {
               "key":"How would you rate the quality of support?",
               "value":"Good",
               "id":"137164167769201638"
            }
         ],
         "custom_variables":[
            {
               "key":"customer_login",
               "value":"mary_brown"
            }
         ],
         "integration_variables":[
            {
               "key":"facebook.id",
               "value":"123456789"
            },
            {
               "...":"..."
            }
         ],
         "goals":[
            {
               "id":71,
               "name":"goal_name",
               "order":{
                  "id":"ABC",
                  "description":"product one",
                  "price":"199",
                  "currency":"CZK"
               }
            },
            {
               "id":72,
               "name":"goal_name",
               "order":{
               }
            }
         ],
         "queue":{
            "duration":20
         },
         "tags":[
            "tag1",
            "tag2",
            "tag3"
         ],
         "timezone": "Europe/Berlin",
         "messages":[
            {
               "author_name":"John Doe",
               "text":"Hello",
               "date":"Wed, 01/23/13 11:40:53 am",
               "timestamp":1358937653,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com"
            },
            {
               "...":"..."
            }
         ],
         "events":[
            {
               "author_name":"John Doe",
               "text":"Hello",
               "date":"Wed, 01/23/13 11:40:53 am",
               "timestamp":1358937653,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com",
               "type":"message"
            },
            {
               "...":"..."
            },
         ],
         "engagement":immediate_start,
         "started_timestamp":1358937653,
         "ended_timestamp":1358939109,
         "ended":"Wed, 01/23/13 12:05:09 pm"
      },
      {
         "...":"..."
      }
   ],
   "total":2,
   "pages":1
}

This method updates the tags assigned to a chat.

Required parameter

Parameter Description
tag array of used tags

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 the 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

Sample request

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

Sample response

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

This function creates new chat for a visitor and returns a 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. Its maximum length is 1024 characters
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

Sample request

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

Sample 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

Sample 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!"

Sample 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

Sample request

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

Sample 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 them.

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

Sample request

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

Sample 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 the list of all currently set canned responses.

Optional parameters

Parameter Description
group defaults to 0
modification_date, modification_by appear if the canned response has been modified

Get a single canned response

CANNED_RESPONSE_ID is obtained from the list of all canned responses.

Path

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

Sample request

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

Sample 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

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

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

Sample 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>

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

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

Sample 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

Sample request

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

Sample response

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

Returns all currently set goals. The active parameter indicates whether a goal is enabled or not.

Get a single goal details

Path

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

Sample request

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

Sample response

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

Returns the 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

The type attribute can take the following values:

Mark a goal as successful

Path

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

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

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

Sample response

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

The GOAL_ID is obtained from the goals list.

Required parameters

Parameter Description
visitor_id obtained using the JavaScript API: LC_API.get_visitor_id()

Optionally you can store additional information about the goal. They can be only retrieved using the API.

Optional parameters

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

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

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

Sample response

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

Creates a new goal.

Required parameters

Parameter Description
name
type

Additional info

The type can take the following values:

The active parameter indicates whether the goal is active or not.

Update a goal

Path

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

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

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

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

The GOAL_ID is obtained from the goals list.

Optional parameters

Parameter Description
name
type

Additional info

The type can take the following values:

The active parameter indicates whether the goal is active or not.

Remove a goal

Path

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

Sample request

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

Sample response

{
  "result": "goal removed successfully"
}

Removes a goal with the given GOAL_ID.

Greetings

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

Available paths

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

Sample request

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

Sample 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>

Sample request

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

Sample 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:

Create a new greeting

Path

[POST] /greetings

Use this function to create a new greeting.

Required properties

Property Description
name greeting name displayed in the LiveChat settings (not visible to your website's 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 a particular group only. Defaults to 0

Greeting rules

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

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

Sample 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:

The default value for operator is equals.

And here's a list of the greeting rules that you can use:

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

Custom variable

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

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

Sample 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

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

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

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

The visitors who have visited the specified sequence of pages will receive the greeting.

Greetings with multiple rules

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

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

Sample 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. The GREETING_ID is obtained from the list of all greetings.

Update greeting name or message

Sample 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

Sample 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

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

Sample 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>

Sample request

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

Sample response

{
  "ok": true
}

Removes a greeting.

Groups

Use this method to get Agent Groups data and also to create new and modify the 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

Sample request

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

Sample 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:

Get a single group details

Path

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

Sample request

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

Sample 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:

The status can take the following values:

Create a new group

Path

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

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

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

Sample 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>

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

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

Sample 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>

Sample request

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

Sample 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

Sample 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

Sample 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

Sample 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

Sample 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 you get your chats from. They can come from i.e. automatic invitations, manual invitations or the visitors can start the chats by 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

Sample 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

Sample 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 have been rated and how they have been rated 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
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

Sample request

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

Sample 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

Sample 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

Sample 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 waited in the queue and 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

Sample 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

Sample 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 the 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

Sample 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

Sample 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 long an agent (or a group or the whole account) was available for chatting during a specified period. When querying for one day, the 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

Sample 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

Sample 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 an agent (or a group) spent on chatting during a specified period. When querying for one day, the 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

Sample 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

Sample 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 the 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:

Chats response time

Path

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

Sample 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

Sample 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 the 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:

Number of simultaneous chats

Path

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

Sample request

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

Sample 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 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

Sample 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

Sample 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

Sample 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

Sample 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

Sample 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

Sample 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

Sample 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

Sample 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 the 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:

Solved tickets

Path

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

Sample 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

Sample 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

Sample 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

Sample 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:

Ticket sources

Path

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

Sample 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

Sample 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 the 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:

Ticket ratings report

Path

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

Sample 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

Sample 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 the tickets that were rated 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

Ticket Ranking

Path

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

Sample request

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

Sample 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

Sample request

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

Sample response

{
  "status":"online"
}

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

Optional parameters

Parameter Description
group defaults to 0

Tags

Using this method, you will be able to create and delete Tags in LiveChat. You can also use it to learn more about the performance of all your Tags.

Available paths

Methods Path
GET, POST /tags
DELETE /tags/<TAG>

List all tags

Path

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

Sample request

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

Sample response

[
  {
    "name": "sales",
    "author":"john.doe@mycompany.com",
    "creation_date":1402989014,
    "count": 
    {
        "inChats":4,
        "inTickets":1
    },
    group:1
  },
  {
    "name": "support",
    "author":"john.doe@mycompany.com",
    "creation_date":1402991857,
    "count": 
    {
        "inChats":0,
        "inTickets":2
    },
    group:1
  }
]

Returns tags from all groups.

Optional parameters

Parameter Description
group returns tags from chosen group

Add a tag

Path

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

Sample request

curl "https://api.livechatinc.com/tags" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "tag=support&\
author=john.doe@mycompany.com&\
group=1"

Sample JSON request

curl "https://api.livechatinc.com/tags" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "tag":"support",
        "author":"john.doe@mycompany.com",
        "group":1  
      }'

Sample response

{
  "name": "support",
  "author":"john.doe@mycompany.com",
  "creation_date":1402989014,
  "count": 
  {
      "inChats":0,
      "inTickets":0
  },
  group:1
}

Adds a new tag. Note that only the owner and the admins are authorized to use this.

Required parameters

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

Delete a tag

Path

[DELETE]   /tags/<TAG>

Sample request

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

Sample JSON request

curl "https://api.livechatinc.com/tags/support" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 DELETE \
  -H Content-type:application/json \
  -d '{
        "group":1
      }' 

Example response

{
  "ok": true
}

Deletes a tag from the chosen group. The agents will no longer be able to tag chats and tickets using this tag.

Required properties

Property Description
tag tag name
group id of the group that the tag is assigned to

Tickets

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

Available paths

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

Sample 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 

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

Additional info:

The results are divided into pages, each containing 25 tickets.

total indicates the total number of tickets.
pages indicstes the total number of pages.

To access next pages of the results, use ?page=<PAGE> parameter.
Please note that the first page's number is 1, not 0.

Get single ticket

Path

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

Sample request

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

Sample response

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

Returns a single ticket item for the given TICKET_ID.

Create a ticket

Path

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

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

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

Sample response

The 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

Sample

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" 

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

Sample 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 the real-time Visitors on your website. You can also use it to display additional information about the visitors in the LiveChat app.

Available paths

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

List all visitors

Path

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

Sample request

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

Sample 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 a list of the visitors on the pages with the 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:

The possible state values returned without any filter are:

The possible state filter values are chatting and queued.

prechat_survey parameter will be available only if the visitor is currently chatting.

custom_variables parameter will be available only if the custom variables are defined in the tracking code.

Add custom visitor details

Path

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

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

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

Sample response

{
  "result": "Visitor details added"
}

Displays additional information about a visitor in LiveChat apps.

For example, if you have your own database with some additional details about your users, you can query this database based on your visitor’s e-mail address, and display the data from your database for an 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 a sample 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 our webhooks tutorial for more information, use cases and to learn how to get started.

Available paths

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

Display configured webhooks

Path

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

Sample request

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

Sample 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 a list of webhooks that have been created in a LiveChat account.

Create a new webhook

Path

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

Sample 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

Sample 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>

Sample request

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

Sample response

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

Deletes a webhook with the given ID.