Configuration API v2

9 minutes reading time • last modified 09/19/2019

Introduction

Welcome to the LiveChat API documentation!

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

Please note that this documentation refers to the API version 2.0.

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 URL path depends on the type of your request. For example, use: https://api.livechatinc.com/agents to get or modify the agents data.

Data centers

LiveChat system operates in two data centers: dal and fra. The default data center is dal.

All the LiveChat OAuth2.0 access tokens have a prefix: dal- or fra-. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.

For example: if the user token starts with fra-, you should add X-Region: fra header. If the token starts with dal- you don't have to specify the header.

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

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

Sample agents list returned in the JSON format

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

JSONP

Sample JSONP request

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

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

Sample JSONP response

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

Error handling

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

HTTP status codes summary

  • 400 – The request is incorrect, please make sure that the passed arguments are matching the format in the method's documentation.
  • 401 – Unauthorized. You attempt to authenticate with an invalid username or API key.
  • 404 – Not Found. You attempt to request a resource which doesn't exist.
  • 500 – Internal Server Error. Something unexpected happened on our end. Please try again or contact our support.

Cross-domain

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

LiveChat API libraries

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 to manage your Agents and to get information about their activities.

MethodsPath
GET, POST/agents
GET, PUT, DELETE/agents/<LOGIN>
POST/agents/<LOGIN>/reset_api_key

List all agents

Returns all LiveChat agents list. Optional parameters:

  • status - returns the agents with one of the following statuses: accepting chats, not accepting chats or offline.

Additional info:

status can be: accepting chats, not accepting chats or offline.
permission can take the following values: owner, administrator, normal.

GET /agents
curl "https://api.livechatinc.com/agents" \a
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
[
  {
    "name": "John Doe",
    "permission": "owner",
    "avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
    "login": "john.doe@mycompany.com",
    "status": "accepting chats"
  },
  ...
]

Get a single agent details

Returns complete details of the agent for the given LOGIN.

Properties

PropertyDescription
loginthe agent's e-mail address
namethe agent's name
login_statuspossible values: accepting chats, not accepting chats; defines the default status for an agent right after the login
permissionpossible values: owner, administrator, normal
daily_summarywhether or not the agent receives a daily summary
job_titledefaults to: Support Agent
avatarpath to the image on Amazon s3
notificationswhether or not the specific notification is enabled
max_chats_countlimit of the concurrent chats
groups[]list of groups the agent is a member of
statuspossible values: accepting chats, not accepting chats, offline; current status of an agent
last_logouttimestamp of the agent's last logout
api_keythe agent's API key (note: agents can access their own API keys only)
GET /agents/<LOGIN>
curl "https://api.livechatinc.com/agents/john.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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"
}

Create a new agent

Creates a new agent in your license.

Required properties

PropertyDescription
loginmust be a correct e-mail address
namestring

Optional properties

PropertyDescription
job_titledefaults to: Support Agent
login_statuspossible values: accepting chats, not accepting chats; defines the default status for an agent right after the login
passwordthe minimum length is 5 (if not provided, an email with the activation link will be sent)
permissionadministrator, normal (default)
groups[]list of group IDs
notificationsobject (required keys: new_visitor, incoming_chat, returning_visitor, queued_visitor, visitor_is_typing, new_goal, accepted values: 0 or 1)
daily_summary0 or 1 (default)
max_chats_countdefaults to 6
POST /agents
curl "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]
     }'
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"
}

Update an agent

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

Optional properties

PropertyDescription
job_title
name
login_statuspossible values: accepting chats, not accepting chats; defines the default status for agent right after login
passwordthe password you want to change
current_passwordwhen changing the password for yourself or for another agent, you need to provide your current password
permissionadministrator, normal (default)
statusaccepting chats, not accepting chats, offline
groups[]list of group IDs
notificationsobject (allowed keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, allowed values: 0 or 1)
daily_summary0 or 1
max_chats_count
work_scheduleravailable only for enterprise plan

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

  • password
  • name
  • job_title
  • daily_summary
  • notifications
  • login_status
  • status
PUT /agents/<LOGIN>
curl "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
     }'
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",
}

Reset an API key

Resets the API key for an agent with a given LOGIN. The return format is the same as in the update an agent method.

POST /agents/<LOGIN>/reset_api_key
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

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.

DELETE /agents/<LOGIN>
curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "result": "jenny.doe@mycompany.com removed successfully"
}

Archives (deprecated)

Please note this API is deprecated. We highly recommend switching to the new Messaging APIs.

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

Available paths

MethodsPath
GET/chats
GET/chats/<CHAT_ID>
POST/chats/<CHAT_ID>/send_transcript
PUT/chats/<CHAT_ID>/tags

Get list of chats (deprecated)

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

Returns all ended chats.

Optional parameters

ParameterDescription
date_fromYYYY-MM-DD Defaults to the beginning of time
date_toYYYY-MM-DD Defaults to today
timezonetimezone in the TZ format (e.g. America/Phoenix)
pagepage number, defaults to 1
visitor_idreturn chats with specified visitor_id
queryreturn chats containing the query
agentreturn chats for given agent login
groupreturn chats for given group id
goalreturn chats for given goal id
has_goal1/0. If 1 is passed, returns chats having any goal
salereturn chats for given sales tracker id
has_sale1/0. If 1 is passed, returns chats having any tracked sale
queued1/0. If 1 is passed, returns chats started from queue
ratefilter chats considering its rating status. Available values: rated, not_rated, rated_good, rated_bad
include_pending1/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
tagged1/0. If 1 is passed, chats with any tag are returned. If 0 is passed, only chats without a tag are returned
comment1/0. If 1 is passed, chats with rating comments are returned
cityfilters by city, values should be entered and are returned in the local language
regionfilters by region. This could be a state, voivodeship, canton, county etc. Values should be entered and are returned in the local language
countryfilters by country name. All values are in english
Additional info
ParameterDescription
goalparameter will appear only if a goal has been reached or there was tracked sale for a particular chat
referrerparameter will appear only if referrer url exists
custom_variablesparameter will be available only if the custom variables are defined in the tracking code
integration_variablesparameter will appear only if a visitor logs in with Facebook
queueparameter 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)
durationis counted in seconds
totaltells you the total number of chats
pagestells you the total number of pages
city, region, countrygeolocation filters have been working for chats since May 11, 2015

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

Note that the results are limited to the latest 25000 records on your LiveChat license, which gives you exactly 1000 pages with 25 chats per page. If you have more than 25000 chats on your license and you want to get them all, you will have to call our API several times.

In the first call, use the data range that covers the first 25000 chats. When making other calls, use the data range that includes the rest of your conversations.

GET /chats
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
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": "",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
      },
      "agents": [
        {
          "display_name": "John Doe",
          "email": "john.doe@mycompany.com"
        }
      ],
      "supervisors": [
        {
          "display_name": "Jane Doe",
          "email": "jane.doe@mycompany.com"
        }
      ],
      "rate": "not_rated",
      "duration": 1456,
      "chat_start_url": "https://livechatinc.com",
      "referrer": "https://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": "sales_tracker_name",
          "type": "sales_tracker",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "order": {
            "id": "ABC",
            "description": "product one",
            "price": "199",
            "currency": "CZK"
          }
        },
        {
          "id": 72,
          "name": "goal_name",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "order": {
            "id": "",
            "description": "",
            "price": "0",
            "currency": ""
          }
        }
      ],
      "queue": {
        "duration": 20
      },
      "tags": ["sales", "support", "feedback"],
      "timezone": "Europe/Berlin",
      "messages": [
        {
          "author_name": "John Doe",
          "text": "Hello",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com"
        }
        // ...
      ],
      "events": [
        {
          "author_name": "John Doe",
          "text": "Hello",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com",
          "type": "message"
        },
        {
          "text": "Mary Brown uploaded the attachment.",
          "date": "Wed, 01/23/13 11:41:02 am",
          "timestamp": 1358937662,
          "type": "attachment",
          "user_type": "visitor",
          "files": ["https://static.livechatinc.com/.../hello.JPG"],
          "author_name": "Mary Brown"
        },
        {
          "author_name": "John Doe",
          "text": "Thanks, fine :)",
          "date": "Wed, 01/23/13 11:41:05 am",
          "timestamp": 1358937665,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com",
          "type": "message"
        },
        {
          "author_name": "Jane Doe",
          "text": "Message from supervisor.",
          "date": "Wed, 01/23/13 11:57:13 am",
          "timestamp": 1358938633,
          "user_type": "supervisor",
          "agent_id": "jane.doe@mycompany.com",
          "type": "message"
        },
        {
          "text": "Mary Brown closed the chat.",
          "date": "Wed, 01/23/13 11:57:14 am",
          "timestamp": 1358937663,
          "type": "event",
          "event_type": "closed",
          "user_type": "visitor"
        }
      ],
      "engagement": immediate_start,
      "started_timestamp": 1358937653,
      "ended_timestamp": 1358939109,
      "ended": "Wed, 01/23/13 12:05:09 pm"
    },
    {
      "...": "..."
    }
  ],
  "total": 2,
  "pages": 1
}

Get single chat (deprecated)

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

Returns a single chat item for the given CHAT_ID.

GET chats/<CHAT_ID>
curl "https://api.livechatinc.com/chats/MH022RD0K5" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
{
  "type": "chat",
  "id": "MH022RD0K5",
  "visitor": {
    "id": "S1355415390.49b8940793",
    "name": "Mary Brown",
    "ip": "85.10.5.156",
    "city": "Central District",
    "country": "Hong Kong",
    "country_code": "HK",
    "timezone": "Asia/Hong_Kong",
    "region": "",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
  },
  "agents": [
    {
      "display_name": "John Doe",
      "email": "john.doe@mycompany.com"
    }
  ],
  "supervisors": [
    {
      "display_name": "Jane Doe",
      "email": "jane.doe@mycompany.com"
    }
  ],
  "rate": "not_rated",
  "duration": 1456,
  "chat_start_url": "https://livechatinc.com",
  "referrer": "https://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": "sales_tracker_name",
      "type": "sales_tracker",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "order": {
        "id": "ABC",
        "description": "product one",
        "price": "199",
        "currency": "CZK"
      }
    },
    {
      "id": 72,
      "name": "goal_name",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "order": {
        "id": "",
        "description": "",
        "price": "0",
        "currency": ""
      }
    }
  ],
  "queue": {
    "duration": 20
  },
  "tags": ["sales", "support", "feedback"],
  "timezone": "Europe/Berlin",
  "messages": [
    {
      "author_name": "John Doe",
      "text": "Hello",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com"
    }
    // ...
  ],
  "events": [
    {
      "author_name": "John Doe",
      "text": "Hello",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com",
      "type": "message"
    },
    {
      "text": "Mary Brown uploaded the attachment.",
      "date": "Wed, 01/23/13 11:41:02 am",
      "timestamp": 1358937662,
      "type": "attachment",
      "user_type": "visitor",
      "files": ["https://static.livechatinc.com/.../hello.JPG"],
      "author_name": "Mary Brown"
    },
    {
      "author_name": "John Doe",
      "text": "Thanks, fine :)",
      "date": "Wed, 01/23/13 11:41:05 am",
      "timestamp": 1358937665,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com",
      "type": "message"
    },
    {
      "author_name": "Jane Doe",
      "text": "Message from supervisor.",
      "date": "Wed, 01/23/13 11:57:13 am",
      "timestamp": 1358938633,
      "user_type": "supervisor",
      "agent_id": "jane.doe@mycompany.com",
      "type": "message"
    },
    {
      "text": "Mary Brown closed the chat.",
      "date": "Wed, 01/23/13 11:57:14 am",
      "timestamp": 1358937663,
      "type": "event",
      "event_type": "closed",
      "user_type": "visitor"
    }
  ],
  "engagement": immediate_start,
  "started_timestamp": 1358937653,
  "ended_timestamp": 1358939109,
  "ended": "Wed, 01/23/13 12:05:09 pm"
}

Update chat tags (deprecated)

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

This method updates the tags assigned to a chat.

Required parameter

ParameterDescription
tagarray of used tags
PUT /chats/<CHAT_ID>/tags
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"
      }'
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
}

Send chat transcript to e-mail

Required parameter

ParameterDescription
toreceiver's email address.
POST /chats/<CHAT_ID>/send_transcript
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"
      }'
Response
{
  "result": "E-mail has been sent to john.doe@mycompany.com."
}

Canned responses

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

Available paths

MethodsPath
GET, POST/canned_responses
GET, PUT, POST/canned_responses/<CANNED_RESPONSE_ID>

List all canned responses

Returns the list of all currently set canned responses.

Optional parameters

ParameterDescription
groupdefaults to 0
modification_date, modification_byappear if the canned response has been modified
GET /canned_responses
curl "https://api.livechatinc.com/canned_responses?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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"]
  },
  {
    "...": "..."
  }
]

Get a single canned response

CANNED_RESPONSE_ID is obtained from the list of all canned responses.

Attributes

AttributeDescription
idid of the canned response
groupid of the group that canned response is assigned to
textcanned response text
creation_datecreation date timestamp
created_bylogin of the canned response's author
tagsan array of canned response's tags
GET /canned_responses/<CANNED_RESPONSE_ID>
curl "https://api.livechatinc.com/canned_responses/3151" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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"]
}

Create a new canned response

Creates a new canned response.

Required properties

PropertyDescription
textresponse text
tagsarray of strings (tags)

Optional properties

PropertyDescription
groupdefaults to 0
POST /canned_responses
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"]
     }'
Response
{
  "id": 3181,
  "group": 0,
  "text": "Have a great day, goodbye.",
  "creation_date": 1358866421,
  "created_by": "john.doe@mycompany.com",
  "tags": ["cu", "bye"]
}

Update a canned response

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

Optional properties

PropertyDescription
textresponse text
tagsarray of strings (tags)
PUT /canned_responses/<CANNED_RESPONSE_ID>
curl "https://api.livechatinc.com/canned_responses/3181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT -d "tags[]=bye"
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"]
}

Remove a canned response

Removes a canned response with the given CANNED_RESPONSE_ID.

DELETE /canned_responses/<CANNED_RESPONSE_ID>
curl "https://api.livechatinc.com/canned_responses/3181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "result": "Canned response removed successfully"
}

Goals

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

Available paths

MethodsPath
GET, POST/goals
GET, PUT, DELETE/goals/<GOAL_ID>
POST/goals/<GOAL_ID>/mark_as_successful

List all goals

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

Optional parameters

ParameterDescription
typetype of the goal: custom_variable, url, api or sales_tracker
GET /goals
curl "https://api.livechatinc.com/goals" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
[
  {
    "id": 1041,
    "name": "purchase",
    "active": 1,
    "type": "url"
  },
  {
    "id": 1181,
    "name": "nike shoes variable",
    "active": 1,
    "type": "custom_variable"
  }
]

Get a single goal details

Returns the goal details for the given GOAL_ID.

Attributes

AttributeDescription
idid of the goal
namegoal name
activewhether or not the goal is enabled
typetype of the goal

Additional info

The type attribute can take the following values:

  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value.
  • url – with two additional parameters: url and match_type with possible values: substring (default), exact.
  • api – with no additional parameters.
  • sales_tracker – with seven additional parameters: sales_tracker_id, value_type, value, currency, time_range, order_field_name and value_field_name
GET /goals/<GOAL_ID
curl "https://api.livechatinc.com/goals/1181" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
{
  "id": 1181,
  "name": "nike shoes variable",
  "active": 1,
  "type": "custom_variable",
  "custom_variable_name": "nike_shoes",
  "custom_variable_value": "true"
}

Mark a goal as successful

The GOAL_ID is obtained from the goals list.

Required parameters

ParameterDescription
visitor_idobtained using the JavaScript API: LC_API.get_visitor_id()

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

Optional parameters

ParameterExample
order_idAP723HVCA721
order_descriptionNike shoes
order_price199.00, only the period is allowed as a separation character
order_currencyUSD
POST /goals/<GOAL_ID>/mark_as_successful
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",
     }'
Response
{
  "result": "goal marked as successful"
}

Add a new goal

Creates a new goal.

Required parameters

ParameterDescription
namename of the goal
typetype of the goal

Additional info

The type can take the following values:

  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value. Both are required.
  • url – with two additional parameters: url (required) and match_type (optional) with possible values: substring (default), exact.
  • api – with no additional parameters.
  • sales_tracker – with optional parameters: value_type (possible values: set, not_set, dynamic), value, currency, time_range, order_field_name, value_field_name and sales_tracker_id

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

POST /goals
curl "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"
     }'
Response
{
  "id": 2231,
  "name": "new goal",
  "active": 1,
  "type": "url",
  "match_type": "exact",
  "url": "http://www.mystore.com/checkout/thank_you"
}

Update a goal

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

The GOAL_ID is obtained from the goals list.

Optional parameters

ParameterDescription
namename of the goal
typetype of the goal
activeactive state of the goal

Additional info

The type can take the following values:

  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value. Both are required.
  • url – with two additional parameters: url (required) and match_type (optional) with possible values: substring (default), exact.
  • api – with no additional parameters.
  • sales_tracker – with optional parameters: order_field_name, value_field_name and sales_tracker_id

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

PUT /goals/<GOAL_ID>
curl "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
     }'
Response
{
  "id": 2231,
  "name": "new goal paused",
  "active": 0,
  "type": "url",
  "match_type": "exact",
  "url": "http://www.mystore.com/checkout/thank_you"
}

Remove a goal

Removes a goal with the given GOAL_ID.

DELETE /goals/<GOAL_ID>
curl "https://api.livechatinc.com/goals/2231" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "result": "goal removed successfully"
}

Greetings

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

Available paths

MethodsPath
GET, POST/greetings
GET, POST, DELETE/greetings/<GREETING_ID>

List all greetings

Returns the list of all greetings.

Optional properties

PropertyDescription
groupGroup number can be specified to get greetings from a given group. If not specified, all greetings will be returned
GET /greetings
curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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!"
    }
  }
]

Get a single greeting

Returns the specified greeting.

Additional info:

  • active – Indicates whether the greeting is enabled or not
  • rules – Returns an array with all the rules for the specified greeting
GET /greetings/<GREETING_ID>
curl "https://api.livechatinc.com/greetings/2411" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
{
  "id": 2411,
  "active": true,
  "name": "Returning visitor",
  "rules": [
    {
      "id": 8191,
      "value": "2",
      "type": "visits_number",
      "operator": "greater_or_equal",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello again!"
  }
}

Create a new greeting

Use this function to create a new greeting.

Required properties

PropertyDescription
namegreeting name displayed in the LiveChat settings (not visible to your website's visitors)
rulesan array of conditions that must be met for the greeting to be displayed. Greeting rules are documented below

Optional properties

PropertyDescription
groupcreates a greeting displayed in a particular group only. Defaults to 0
POST /greetings
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"
          }
        ]

Greeting rules

Greeting rules are the conditions that must be met for a greeting to be displayed.

Each greeting rule can contain an operator. Here's a list of possible operators:

  • equals,
  • doesnt_equal,
  • lower_than,
  • lower_or_equal,
  • greater_than,
  • greater_or_equal,
  • contains,
  • doesnt_contain.

The default value for operator is equals.

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

RuleDescription
visit_time_siteAfter a visitor has spent a certain amount of time on the site
visit_time_pageAfter a visitor has spent a certain amount of time on a page
url_currentFor the visitors on specific pages
url_visitedWhen a visitor has visited specific pages
pages_view_numberFor the visitors who have seen a page for a number of times
url_referrerWhen the visitor has arrived from a referring page
geolocationFor the visitors from specific countries or cities
visits_numberFor the returning visitors
search_keywordWhen a visitor has searched for a specific keyword
custom_variableThe greeting will be sent when the specified variable is met documented below
url_funnelThe visitors who visit the specified sequence of websites will receive the greeting documented below
/greetings
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"
          }
        ]
      }'
Response
{
  "id": 2451,
  "active": true,
  "name": "my custom invitation",
  "rules": [
    {
      "id": 8241,
      "value": "2",
      "type": "visits_number",
      "operator": "greater_or_equal",
      "condition": "and"
    },
    {
      "id": 8251,
      "value": "15",
      "type": "visit_time_page",
      "operator": "greater_than",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}

Custom variable

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

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

URL Funnel

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

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"
              }
            ]
          }
        ]
      }'
Response
{
  "id": 2441,
  "active": true,
  "name": "url funnel type greeting",
  "rules": [
    {
      "id": 8231,
      "type": "url_funnel",
      "condition": "and",
      "urls": [
        {
          "url": "mystore.com/shoes",
          "operator": "equals"
        },
        {
          "url": "cart",
          "operator": "contains"
        }
      ]
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}

Greetings with multiple rules

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

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"
          }
        ]
      }'
Response
{
  "id": 2471,
  "active": true,
  "name": "my custom invitation",
  "rules": [
    {
      "id": 8261,
      "type": "custom_variable",
      "operator": "equals",
      "condition": "and",
      "variable_name": "empty_cart",
      "variable_value": "true"
    },
    {
      "id": 8271,
      "value": "15",
      "type": "visit_time_site",
      "operator": "equals",
      "condition": "and"
    },
    {
      "id": 8281,
      "value": "shoes",
      "type": "url_current",
      "operator": "contains",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}

Update a greeting

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

Update greeting name or message

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

PUT /greetings/<GREETING_ID>
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"

Activate and deactivate greetings

Activate or deactivate a greeting using this request.

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

Change greetings rules

Change the rules of your greetings with this request.

PUT /greetings/<GREETING_ID>
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"
Response
{
  "id": 2491,
  "active": false,
  "name": "athletic shoes",
  "rules": [
    {
      "id": 8371,
      "type": "custom_variable",
      "operator": "equals",
      "condition": "and",
      "variable_name": "athletic_shoes",
      "variable_value": "true"
    }
  ],
  "properties": {
    "active": "0",
    "greeting-message_text": "Hi, are you looking for some athletic shoes"
  }
}

Remove a greeting

Removes a greeting.

DELETE /greetings/<GREETING_ID>
curl "https://api.livechatinc.com/greetings/2491" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "ok": true
}

Groups

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

Available paths

MethodsPath
GET, POST/groups
GET, PUT, DELETE/groups/<GROUP_ID>

List all groups

Returns all created groups.

Additional info:

  • language specifies the chat window language for the particular group.
  • agents list contains all members of the particular group. The group with id 0 doesn't return the agents list because it always contains all agents from the license and it cannot be modified.
GET /groups
curl "https://api.livechatinc.com/groups" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
[
  {
    "id": 0,
    "name": "All operators",
    "language": "en",
    "status": "accepting chats"
  },
  {
    "id": 1,
    "name": "Invoicing",
    "language": "en",
    "agents": ["jane.doe@mycompany.com"],
    "status": "offline"
  },
  {
    "id": 2,
    "name": "Sales",
    "language": "en",
    "agents": ["john.doe@mycompany.com", "jenny.doe@mycompany.com"],
    "status": "not accepting chats"
  },
  {
    "id": 3,
    "name": "Technical Support",
    "language": "en",
    "agents": ["john.doe@mycompany.com"],
    "status": "accepting chats"
  }
]

Get a single group details

Returns group details for the given GROUP_ID.

Attributes

AttributeDescription
idid of the group
namegroup name
languagegroup language (defaults to English). See the list of supported languages
agentsan array of group members' logins
statuscurrent status of the group

Additional info:

The status can take the following values:

  • accepting chats – when at least one agent from the group is logged in and has the accepting chats status.
  • not accepting chats – when at least one agent from the group is logged in but has the not accepting chats status.
  • offline – when all agents from the group are offline.
GET /groups/<GROUP_ID>
curl "https://api.livechatinc.com/groups/2" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
{
  "id": 2,
  "name": "Sales",
  "language": "en",
  "agents": ["john.doe@mycompany.com", "jenny.doe@mycompany.com"],
  "status": "accepting chats"
}

Create a new group

Creates a new group in your license.

Required properties

PropertyDescription
namegroup name
agentsan array of LiveChat users' logins (e-mails)

Optional properties

PropertyDescription
languagegroup language (defaults to English). See the list of supported languages
POST /groups
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": [
          "jenny.doe@mycompany.com",
          "john.doe@mycompany.com"
        ]
      }'
Response
{
  "id": 4,
  "name": "Human Resources",
  "language": "en",
  "agents": ["jenny.doe@mycompany.com", "john.doe@mycompany.com"],
  "status": "offline"
}

Update a group

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

Optional properties

PropertyDescription
namegroup name
languagesee the list of supported languages
agentsan array of LiveChat users' logins (e-mails)
PUT /groups/<GROUP_ID>
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": [
          "john.doe@mycompany.com",
          "jane.doe@mycompany.com"
        ]
      }'
Response
{
  "id": 3,
  "name": "Quality Assurance",
  "language": "en",
  "agents": ["john.doe@mycompany.com", "jane.doe@mycompany.com"],
  "status": "offline"
}

Remove a group

Removes a group with the given GROUP_ID.

DELETE /groups/<GROUP_ID>
curl "https://api.livechatinc.com/groups/4" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "result": "group removed successfully"
}

Status

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

Available paths

MethodsPath
GET/status

Get status

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

Optional parameters

ParameterDescription
groupdefaults to 0
GET /status
curl "https://api.livechatinc.com/status/1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
Response
{
  "status": "online"
}

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

MethodsPath
GET, POST/tags
DELETE/tags/<TAG>

List all tags

Returns tags from all groups.

Optional parameters

ParameterDescription
groupreturns tags from chosen group
GET /tags
curl "https://api.livechatinc.com/tags\
      ?group=1" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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
  }
]

Add a tag

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

Required parameters

ParameterDescription
authoragent login
tagname of a tag
groupid of the group that tag will be added to
POST /tags
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
      }'
Response
{
  "name": "support",
  "author": "john.doe@mycompany.com",
  "creation_date": 1402989014,
  "count": {
    "inChats": 0,
    "inTickets": 0
  },
  "group": 1
}

Delete a tag

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

Required properties

PropertyDescription
tagtag name
groupid of the group that the tag is assigned to
DELETE /tags/<TAG>
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
      }'
Response
{
  "ok": true
}

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

MethodsPath
GET/tickets/<TICKET_ID>
POST/tickets
PUT/tickets/<TICKET_ID>/tags

Get list of tickets

Returns all tickets.

Optional parameters

ParameterDescription
date_fromYYYY-MM-DD. Returns the tickets with any of their activities matching the date. Defaults to the beginning of time
date_toYYYY-MM-DD. Returns the tickets with any of their activities matching the date. Defaults to today
pagepage number, defaults to 1
assignedif 0, returns only the unassigned tickets. If 1, returns only the tickets assigned to any agent
orderorders the tickets by date of the last ticket modification. Possible values: desc, asc. Defaults to desc
statusnot set by default. Possible values: open, pending, solved or spam
assigneereturn the tickets assigned to the given agent's login
queryreturn the tickets containing the query
requester[mail]returns the tickets assigned to the given requester
groupreturns the tickets for the given group
sourcereturns the tickets for the given source. Possible values: lc2 (created from archives), mail, facebook, agent-app-manual (created manually), chat-window (created from ticket form)
tagreturns the statistics for the specified tag
tagged1/0. If 1 is passed, returns the tickets with any tag. If 0 passed, returns the tickets with no tags

Additional info:

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

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

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

GET /tickets
curl "https://api.livechatinc.com/tickets?\
date_from=2013-11-15&\
status=open" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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"]
    }
    // ...
  ]
}

Get single ticket

Returns a single ticket item for the given TICKET_ID.

GET /tickets/<TICKET_ID>
curl "https://api.livechatinc.com/tickets/5FUED" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2
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"]
    }
    // ...
  ]
}

Create a ticket

Creates a new ticket.

Required parameters

ParameterDescription
messagerequester's message
requester[mail]requester's email address

Optional parameters

ParameterDescription
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
subjectticket subject. Defaults to (no subject)
grouplist of groups. Must be an array with group IDs. Defaults to [0]
POST /tickets
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"
      }
     }'
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"]
    }
    // ...
  ]
}

Update ticket tags

Updates tags associated with the ticket.

Required parameters

ParameterDescription
tagarray of used tags
PUT /tickets/<TICKET_ID>/tags
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"]
     }'
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"
  ],
  // ...
  ]
}

Webhooks (deprecated)

Please note this API is deprecated. We highly recommend switching to the new Messaging APIs.

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

Check out our webhooks tutorial for more information, use cases and to learn how to get started.

Available paths

MethodsPath
GET/webhooks
POST/webhooks
DELETE/webhooks/<WEBHOOK_ID>

Display configured webhooks

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

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

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

Create a new webhook

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

Creates a new webhook.

Required properties

PropertyDescription
event_typemust be one of chat_started, chat_ended, chat_changed, visitor_queued, ticket_created or canned_response_changed
data_typesdetermines what information the webhook will contain
urlthe URL address the webhook will be sent to

Additional info:

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

PropertyDescription
chat_startedwhen the chat is started
chat_endedwhen the chat is ended
chat_changedwhen the chat is tagged
visitor_queuedwhen the visitor enters the queue before a chat
ticket_createdwhen a new ticket is created
canned_response_changedwhen a canned response is created, modified or deleted

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

PropertyDescription
chatonly supported in chat_started, chat_changed and chat_ended event types
visitoronly supported in chat_started, chat_ended, chat_changed and visitor_queued event types
pre_chat_surveyonly supported in chat_started and chat_ended event types
ticketonly supported in ticket_created event type
canned_responseonly supported in canned_response_changed event type
POST /webhooks
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
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"
    }
  ]
}

Delete a webhook

Please note this method is deprecated. We highly recommend switching to the new Messaging APIs.

Deletes a webhook with the given ID.

DELETE /webhooks/<ID>
curl "https://api.livechatinc.com/webhooks/39612eee5(...)" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X DELETE
Response
{
  "result": "Push notification removed successfully"
}

Visitors

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

Available paths

MethodsPath
GET/visitors
POST/visitors/<VISITOR_ID>/details

List all visitors

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

Optional parameters

ParameterDescription
stateparameter 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
countparameter will allow you to return the number of visitors (when the value is set to 1) instead of all the available information (when it is set to 0). The parameter is set to 0 by default

Additional info:

The possible state values returned without any filter are:

  • browsing
  • chatting
  • logging into chat
  • queued
  • invited
  • refused invitation
  • chat closed

The possible state filter values are chatting and queued.

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

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

GET /visitors
curl "https://api.livechatinc.com/visitors?
state=chatting&\
group[]=0" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 -g
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
  }
  // (...)
]