Configuration API

Introduction

Welcome to the LiveChat API documentation!

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

Please note that this documentation refers to the API version 2.0. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...

Basic API usage

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

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 OAuth 2.1 access tokens have a prefix: dal: or fra:. This prefix indicates the data center they belong to. If you need to specify the data center while making an API call, simply add the X-Region: <token_prefix> optional header.

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

If you get the Misdirected request error, use the prefix returned in the error as the value of X-Region.

Authentication

There are two common authorization methods supported: OAuth 2.1 and Personal Access Token (PAT).

OAuth 2.1

Example REST API call using OAuth 2.1 access_token:

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

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

It is the most secure way of making API calls. With this flow, you will get access only to some parts of LiveChat account, such as reading agents list.

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

Personal Access Token

Personal Access Tokens (PATs) are generated per Agent. They use Basic authentication scheme. You can create a PAT from Developer Console. For more guidelines on creating PATs, check out this tutorial.

Example REST API call using a PAT:

curl "https://api.livechatinc.com/groups" \
-H "Authorization: Basic <email>:<PAT>" \
-H "X-API-Version: 2"

💡 When sending authorization credentials in a header, the email:PAT string has to be base64-encoded. Alternatively, enter your credentials in the Authorization tab in Postman, which will automatically encode them for you (see the image below).

Enter LiveChat auth credentials in Postman

Data format

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

Sample agents list returned in the JSON format

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

JSONP

Sample JSONP request

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

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

Sample JSONP response

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

Error handling

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

HTTP status codes summary

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

Cross-domain

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

LiveChat API libraries

You can call the LiveChat API using librariers written in backend languages. To authorize your requests while using those libraries, use a Personal Access Token.

PHP library for LiveChat API, hosted on Github.
node.js library for LiveChat API, hosted on Github.
Ruby library for LiveChat API, hosted on Github.
C# library for LiveChat API, hosted on Github.

External LiveChat API libraries

R library for LiveChat API, hosted on Github.

Agents

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

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

List all agents

Returns all LiveChat agents list.

Required scopes

agents--all:ro

Or, agents_read if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Optional parameters

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

Copied!

curl "https://api.livechatinc.com/agents" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \
  -H X-API-Version:2

Response

Copied!

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

Get a single agent details

Returns complete details of the agent for the given LOGIN.

Required scopes

agents--all:ro

Or, agents_read if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Parameters

Parameter	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

GET /agents/<LOGIN>

Copied!

curl "https://api.livechatinc.com/agents/john.doe@mycompany.com" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "login": "john.doe@mycompany.com",
  "name": "John Doe",
  "login_status": "accepting chats",
  "permission": "owner",
  "daily_summary": 1,
  "job_title": "Support Agent",
  "avatar": "livechat.s3.amazonaws.com/1011121/all/avatars/bdd8924fcbcdbddbeaf60c19b238b0b0.jpg",
  "notifications": {
    "new_visitor": 1,
    "returning_visitor": 1,
    "queued_visitor": 1,
    "visitor_is_typing": 0,
    "new_goal": 1
  },
  "max_chats_count": 6,
  "groups": [
    {
      "id": 1,
      "name": "Sales"
    },
    {
      "id": 2,
      "name": "Technical Support"
    }
  ],
  "status": "accepting chats",
  "last_logout": 1358427204
}

Create a new agent

Creates a new agent in your license.

Required scopes

accounts--all:r
agents--all:rw (only for the pay per seat pricing model)

Or, agents_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Required parameters

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

Optional parameters

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

POST /agents

Copied!

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

Response

Copied!

{
  "login": "jenny.doe@mycompany.com",
  "name": "Jenny Doe",
  "login_status": "accepting chats",
  "permission": "administrator",
  "daily_summary": 1,
  "job_title": "Support Agent",
  "avatar": "livechat.s3.amazonaws.com/default/avatars/45bcb5f592dbf5aac8f88dcfd6bc937c.png",
  "notifications": {
    "new_visitor": 1,
    "returning_visitor": 1,
    "queued_visitor": 1,
    "visitor_is_typing": 0,
    "new_goal": 1
  },
  "max_chats_count": 6,
  "groups": [
    {
      "id": 1,
      "name": "Sales"
    },
    {
      "id": 2,
      "name": "Technical Support"
    }
  ],
  "status": "offline",
  "last_logout": 0
}

Update an agent

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

Required scopes

agents--my:rw

Or, agents_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Optional parameters

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

password
name
job_title
daily_summary
notifications
login_status
status

PUT /agents/<LOGIN>

Copied!

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

Response

Copied!

{
  "login": "jenny.doe@mycompany.com",
  "name": "Jenny Doe",
  "login_status": "not accepting chats",
  "permission": "administrator",
  "daily_summary": 1,
  "job_title": "Support Agent",
  "avatar": "livechat.s3.amazonaws.com/default/avatars/45bcb5f592dbf5aac8f88dcfd6bc937c.png",
  "notifications": {
    "new_visitor": 1,
    "returning_visitor": 1,
    "queued_visitor": 1,
    "visitor_is_typing": 0,
    "new_goal": 1
  },
  "max_chats_count": 2,
  "work_scheduler":{
    "sunday":{
      "enabled":0,
      "start":"11:00",
      "end":"17:00"
    },
    "monday":{
      "enabled":1,
      "start":"09:00",
      "end":"17:00"
    },
    ...
    "saturday":{
      "enabled":0,
      "start":"09:00",
      "end":"17:00"
    }
  },
  "groups": [
    {
      "id": 1,
      "name": "Sales"
    },
    {
      "id": 2,
      "name": "Technical Support"
    }
  ],
  "status": "not accepting chats",
  "last_logout": 0
}

Remove an agent

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

Required scopes

agents--all:rw

Or, agents_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

DELETE /agents/<LOGIN>

Copied!

curl "https://api.livechatinc.com/agents/jenny.doe@mycompany.com" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

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

Archives (deprecated)

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

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

Available paths

Methods	Path
`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.

Required scopes

archives_read

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
`sale`	return chats for given sales tracker id
`has_sale`	`1/0`. If 1 is passed, returns chats having any tracked sale
`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. They may appear with some delay because of caching reasons
`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 has been reached or there was tracked sale for a particular chat
`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.

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

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

GET /chats

Copied!

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

Response

Copied!

{
  "chats": [
    {
      "type": "chat",
      "id": "MH022RD0K5",
      "visitor": {
        "id": "S1355415390.49b8940793",
        "name": "Mary Brown",
        "ip": "85.10.5.156",
        "city": "Central District",
        "country": "Hong Kong",
        "country_code": "HK",
        "timezone": "Asia/Hong_Kong",
        "region": "",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
      },
      "agents": [
        {
          "display_name": "John Doe",
          "email": "john.doe@mycompany.com"
        }
      ],
      "supervisors": [
        {
          "display_name": "Jane Doe",
          "email": "jane.doe@mycompany.com"
        }
      ],
      "rate": "not_rated",
      "duration": 1456,
      "chat_start_url": "https://livechatinc.com",
      "referrer": "https://example.com",
      "group": [0],
      "started": "Wed, 01/23/13 11:40:53 am",
      "prechat_survey": [
        {
          "key": "Name:",
          "value": "",
          "id": "13589376348060238"
        },
        {
          "key": "E-mail:",
          "value": "",
          "id": "135893763480606511"
        }
      ],
      "postchat_survey": [
        {
          "key": "How would you rate the quality of support?",
          "value": "Good",
          "id": "137164167769201638"
        }
      ],
      "custom_variables": [
        {
          "key": "customer_login",
          "value": "mary_brown"
        }
      ],
      "integration_variables": [
        {
          "key": "facebook.id",
          "value": "123456789"
        },
        {
          "key": "facebook.email",
          "value": "mary.brown@email.com"
        }
        // ...
      ],
      "goals": [
        {
          "id": 71,
          "name": "sales_tracker_name",
          "type": "sales_tracker",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "order": {
            "id": "ABC",
            "description": "product one",
            "price": "199",
            "currency": "CZK"
          }
        },
        {
          "id": 72,
          "name": "goal_name",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "order": {
            "id": "",
            "description": "",
            "price": "0",
            "currency": ""
          }
        }
      ],
      "queue": {
        "duration": 20
      },
      "tags": ["sales", "support", "feedback"],
      "timezone": "Europe/Berlin",
      "messages": [
        {
          "author_name": "John Doe",
          "text": "Hello",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com"
        }
        // ...
      ],
      "events": [
        {
          "author_name": "John Doe",
          "text": "Hello",
          "date": "Wed, 01/23/13 11:40:53 am",
          "timestamp": 1358937653,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com",
          "type": "message"
        },
        {
          "text": "Mary Brown uploaded the attachment.",
          "date": "Wed, 01/23/13 11:41:02 am",
          "timestamp": 1358937662,
          "type": "attachment",
          "user_type": "visitor",
          "files": ["https://static.livechatinc.com/.../hello.JPG"],
          "author_name": "Mary Brown"
        },
        {
          "author_name": "John Doe",
          "text": "Thanks, fine :)",
          "date": "Wed, 01/23/13 11:41:05 am",
          "timestamp": 1358937665,
          "user_type": "agent",
          "agent_id": "john.doe@mycompany.com",
          "type": "message"
        },
        {
          "author_name": "Jane Doe",
          "text": "Message from supervisor.",
          "date": "Wed, 01/23/13 11:57:13 am",
          "timestamp": 1358938633,
          "user_type": "supervisor",
          "agent_id": "jane.doe@mycompany.com",
          "type": "message"
        },
        {
          "text": "Mary Brown closed the chat.",
          "date": "Wed, 01/23/13 11:57:14 am",
          "timestamp": 1358937663,
          "type": "event",
          "event_type": "closed",
          "user_type": "visitor"
        }
      ],
      "engagement": immediate_start,
      "started_timestamp": 1358937653,
      "ended_timestamp": 1358939109,
      "ended": "Wed, 01/23/13 12:05:09 pm"
    },
    {
      "...": "..."
    }
  ],
  "total": 2,
  "pages": 1
}

Get single chat (deprecated)

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.

Required scopes

archives_read

GET chats/<CHAT_ID>

Copied!

curl "https://api.livechatinc.com/chats/MH022RD0K5" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "type": "chat",
  "id": "MH022RD0K5",
  "visitor": {
    "id": "S1355415390.49b8940793",
    "name": "Mary Brown",
    "ip": "85.10.5.156",
    "city": "Central District",
    "country": "Hong Kong",
    "country_code": "HK",
    "timezone": "Asia/Hong_Kong",
    "region": "",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
  },
  "agents": [
    {
      "display_name": "John Doe",
      "email": "john.doe@mycompany.com"
    }
  ],
  "supervisors": [
    {
      "display_name": "Jane Doe",
      "email": "jane.doe@mycompany.com"
    }
  ],
  "rate": "not_rated",
  "duration": 1456,
  "chat_start_url": "https://livechatinc.com",
  "referrer": "https://example.com",
  "group": [0],
  "started": "Wed, 01/23/13 11:40:53 am",
  "prechat_survey": [
    {
      "key": "Name:",
      "value": "",
      "id": "13589376348060238"
    },
    {
      "key": "E-mail:",
      "value": "",
      "id": "135893763480606511"
    }
  ],
  "postchat_survey": [
    {
      "key": "How would you rate the quality of support?",
      "value": "Good",
      "id": "137164167769201638"
    }
  ],
  "custom_variables": [
    {
      "key": "customer_login",
      "value": "mary_brown"
    }
  ],
  "integration_variables": [
    {
      "key": "facebook.id",
      "value": "123456789"
    },
    {
      "key": "facebook.email",
      "value": "mary.brown@email.com"
    }
    // ...
  ],
  "goals": [
    {
      "id": 71,
      "name": "sales_tracker_name",
      "type": "sales_tracker",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "order": {
        "id": "ABC",
        "description": "product one",
        "price": "199",
        "currency": "CZK"
      }
    },
    {
      "id": 72,
      "name": "goal_name",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "order": {
        "id": "",
        "description": "",
        "price": "0",
        "currency": ""
      }
    }
  ],
  "queue": {
    "duration": 20
  },
  "tags": ["sales", "support", "feedback"],
  "timezone": "Europe/Berlin",
  "messages": [
    {
      "author_name": "John Doe",
      "text": "Hello",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com"
    }
    // ...
  ],
  "events": [
    {
      "author_name": "John Doe",
      "text": "Hello",
      "date": "Wed, 01/23/13 11:40:53 am",
      "timestamp": 1358937653,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com",
      "type": "message"
    },
    {
      "text": "Mary Brown uploaded the attachment.",
      "date": "Wed, 01/23/13 11:41:02 am",
      "timestamp": 1358937662,
      "type": "attachment",
      "user_type": "visitor",
      "files": ["https://static.livechatinc.com/.../hello.JPG"],
      "author_name": "Mary Brown"
    },
    {
      "author_name": "John Doe",
      "text": "Thanks, fine :)",
      "date": "Wed, 01/23/13 11:41:05 am",
      "timestamp": 1358937665,
      "user_type": "agent",
      "agent_id": "john.doe@mycompany.com",
      "type": "message"
    },
    {
      "author_name": "Jane Doe",
      "text": "Message from supervisor.",
      "date": "Wed, 01/23/13 11:57:13 am",
      "timestamp": 1358938633,
      "user_type": "supervisor",
      "agent_id": "jane.doe@mycompany.com",
      "type": "message"
    },
    {
      "text": "Mary Brown closed the chat.",
      "date": "Wed, 01/23/13 11:57:14 am",
      "timestamp": 1358937663,
      "type": "event",
      "event_type": "closed",
      "user_type": "visitor"
    }
  ],
  "engagement": immediate_start,
  "started_timestamp": 1358937653,
  "ended_timestamp": 1358939109,
  "ended": "Wed, 01/23/13 12:05:09 pm"
}

Update chat tags (deprecated)

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 scopes

archives_write

Required parameters

Parameter	Description
`tag`	array of used tags

PUT /chats/<CHAT_ID>/tags

Copied!

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

Response

Copied!

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

Send chat transcript to e-mail

Required scopes

archives_read

Required parameters

Parameter	Description
`to`	receiver's email address.

POST /chats/<THREAD_ID>/send_transcript

Copied!

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

Response

Copied!

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

Canned responses

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

Available paths

Methods	Path
`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.

Required scopes

canned_responses_read

Optional parameters

Parameter	Description
`group`	defaults to `0`

Additional info

modification_date, modification_by - appear in the response if the canned response has been modified.

GET /canned_responses

Copied!

curl "https://api.livechatinc.com/canned_responses?group=1" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

[
  {
    "id": 3151,
    "group": 1,
    "text": "Can I help you with anything else?",
    "creation_date": 1358257181,
    "created_by": "john.doe@mycompany.com",
    "tags": ["help", "else"]
  },
  {
    "id": 3161,
    "group": 1,
    "text": "What product are you interested in?",
    "creation_date": 1358257229,
    "created_by": "john.doe@mycompany.com",
    "modification_date": 1358864338,
    "modified_by": "jenny.doe@mycompany.com",
    "tags": ["product", "interest"]
  },
  {
    "...": "..."
  }
]

Get a single canned response

CANNED_RESPONSE_ID is obtained from the list of all canned responses.

Required scopes

canned_responses_read

Parameters

Parameter	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

GET /canned_responses/<CANNED_RESPONSE_ID>

Copied!

curl "https://api.livechatinc.com/canned_responses/3151" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

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

Create a new canned response

Creates a new canned response.

Required scopes

canned_responses_write

Required parameters

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

Optional parameters

Parameter	Description
`group`	defaults to 0

POST /canned_responses

Copied!

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

Response

Copied!

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

Update a canned response

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

Required scopes

canned_responses_write

Optional parameters

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

PUT /canned_responses/<CANNED_RESPONSE_ID>

Copied!

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

Response

Copied!

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

Remove a canned response

Removes a canned response with the given CANNED_RESPONSE_ID.

Required scopes

canned_responses_write

DELETE /canned_responses/<CANNED_RESPONSE_ID>

Copied!

curl "https://api.livechatinc.com/canned_responses/3181" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

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

Goals

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

Available paths

Methods	Path
`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.

Required scopes

goals_read

Optional parameters

Parameter	Description
`type`	type of the goal: `custom_variable`, `url`, `api` or `sales_tracker`

GET /goals

Copied!

curl "https://api.livechatinc.com/goals" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

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

Get a single goal details

Returns the goal details for the given GOAL_ID.

Required scopes

goals_read

Parameters

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

custom_variable – with two additional parameters: custom_variable_name, custom_variable_value.
url – with two additional parameters: url and match_type with possible values: substring (default), exact.
api – with no additional parameters.
sales_tracker – with seven additional parameters: sales_tracker_id, value_type, value, currency, time_range, order_field_name and value_field_name

GET /goals/<GOAL_ID

Copied!

curl "https://api.livechatinc.com/goals/1181" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

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

Mark a goal as successful

The GOAL_ID is obtained from the goals list.

Required scopes

goals_write

Required parameters

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`

POST /goals/<GOAL_ID>/mark_as_successful

Copied!

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

Response

Copied!

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

Add a new goal

Creates a new goal.

Required scopes

goals_write

Required parameters

Parameter	Description
`name`	name of the goal
`type`	type 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

Copied!

curl "https://api.livechatinc.com/goals" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"new goal",
        "type":"url",
        "url":"http://www.mystore.com/checkout/thank_you",
        "match_type":"exact"
     }'

Response

Copied!

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

Update a goal

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

The GOAL_ID is obtained from the goals list.

Required scopes

goals_write

Optional parameters

Parameter	Description
`name`	name of the goal
`type`	type of the goal
`active`	active 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>

Copied!

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

Response

Copied!

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

Remove a goal

Removes a goal with the given GOAL_ID.

Required scopes

goals_write

DELETE /goals/<GOAL_ID>

Copied!

curl "https://api.livechatinc.com/goals/2231" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

{
  "result": "goal removed successfully"
}

Greetings

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

Available paths

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

List all greetings

Returns the list of all greetings.

Required scopes

greetings_read

Optional parameters

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

GET /greetings

Copied!

curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

[
  {
    "id": 2291,
    "active": true,
    "name": "Time on site: 5 sec",
    "rules": [
      {
        "id": 8201,
        "value": "5",
        "type": "visit_time_site",
        "operator": "equals",
        "condition": "and"
      }
    ],
    "properties": {
      "active": "1",
      "greeting-message_text": "Hello, how may I help you?"
    }
  },
  {
    "id": 2411,
    "active": true,
    "name": "Returning visitor",
    "rules": [
      {
        "id": 8191,
        "value": "2",
        "type": "visits_number",
        "operator": "greater_or_equal",
        "condition": "and"
      }
    ],
    "properties": {
      "active": "1",
      "greeting-message_text": "Hello again!"
    }
  }
]

Get a single greeting

Returns the specified greeting.

Required scopes

greetings_write

Additional info

active – Indicates whether the greeting is enabled or not
rules – Returns an array with all the rules for the specified greeting

GET /greetings/<GREETING_ID>

Copied!

curl "https://api.livechatinc.com/greetings/2411" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "id": 2411,
  "active": true,
  "name": "Returning visitor",
  "rules": [
    {
      "id": 8191,
      "value": "2",
      "type": "visits_number",
      "operator": "greater_or_equal",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello again!"
  }
}

Create a new greeting

Use this function to create a new greeting.

Required scopes

greetings_write

Required parameters

Parameter	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 parameters

Parameter	Description
`group`	creates a greeting displayed in a particular group only. Defaults to `0`
`active`	creates a greeting, which is active or inactive. Defaults to `1`
`subtype`	possible values: `announcement`; you can have up to 10 `announcement` greetings; if a given `announcement` greeting is canceled by a customer, it'll never be displayed to that customer again

POST /greetings

Copied!

curl "https://api.livechatinc.com/greetings" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"my custom invitation",
        "rules":[
          {
            "type":"visit_time_page",
            "value":15,
            "operator":"greater_than"
          },
          {
            "type":"visits_number",
            "value":2,
            "operator":"greater_or_equal"
          }
        ]

Greeting rules

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

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

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

The default value for operator is equals.

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

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

/greetings

Copied!

curl "https://api.livechatinc.com/greetings" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"my custom invitation",
        "rules":[
          {
            "type":"visit_time_page",
            "value":15,
            "operator":"greater_than"
          },
          {
            "type":"visits_number",
            "value":2,
            "operator":"greater_or_equal"
          }
        ]
      }'

Response

Copied!

{
  "id": 2451,
  "active": true,
  "name": "my custom invitation",
  "rules": [
    {
      "id": 8241,
      "value": "2",
      "type": "visits_number",
      "operator": "greater_or_equal",
      "condition": "and"
    },
    {
      "id": 8251,
      "value": "15",
      "type": "visit_time_page",
      "operator": "greater_than",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}

Custom variable

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

/greetings

Copied!

curl "https://api.livechatinc.com/greetings\
  ?group=1" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"custom variable type greeting",
        "rules":[
          {
            "type":"custom_variable",
            "variable_name":"my_custom_var",
            "variable_value":"var_value"
            "operator":"contains"
          }
        ]
      }'

Response

Copied!

{
  "id": 2431,
  "active": true,
  "name": "custom variable type greeting",
  "rules": [
    {
      "id": 8221,
      "type": "custom_variable",
      "operator": "contains",
      "condition": "and",
      "variable_name": "my_custom_var",
      "variable_value": "var_value"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}

URL Funnel

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

/greetings

Copied!

curl "https://api.livechatinc.com/greetings" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"url funnel type greeting",
        "rules":[
          {
            "type":"url_funnel",
            "urls":[
              {
                "url":"mystore.com/shoes",
                "operator":"equals"
              },
              {
                "url":"cart",
                "operator":"contains"
              }
            ]
          }
        ]
      }'

Response

Copied!

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

Greetings with multiple rules

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

/greetings

Copied!

curl "https://api.livechatinc.com/greetings" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
        "name":"my custom invitation",
        "rules":[
          {
            "type":"visit_time_site",
            "value":15
          },
          {
            "type":"custom",
            "variable_name":"empty_cart",
            "variable_value":true
          },
          {
            "type":"url_current",
            "value":"shoes",
            "operator":"contains"
          }
        ]
      }'

Response

Copied!

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

Update a greeting

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

Update greeting name or message

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

Required scopes

greetings_write

PUT /greetings/<GREETING_ID>

Copied!

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

Activate and deactivate greetings

Activate or deactivate a greeting using this request.

Required scopes

greetings_write

PUT /greetings/<GREETING_ID>

Copied!

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

Change greetings rules

Change the rules of your greetings with this request.

Required scopes

greetings_write

PUT /greetings/<GREETING_ID>

Copied!

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

Response

Copied!

{
  "id": 2491,
  "active": false,
  "name": "athletic shoes",
  "rules": [
    {
      "id": 8371,
      "type": "custom_variable",
      "operator": "equals",
      "condition": "and",
      "variable_name": "athletic_shoes",
      "variable_value": "true"
    }
  ],
  "properties": {
    "active": "0",
    "greeting-message_text": "Hi, are you looking for some athletic shoes"
  }
}

Remove a greeting

Removes a greeting.

Required scopes

greetings_write

DELETE /greetings/<GREETING_ID>

Copied!

curl "https://api.livechatinc.com/greetings/2491" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

{
  "ok": true
}

Groups

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

Returns all created groups.

Required scopes

groups--all:ro

Or, groups_read if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Additional info

language specifies the chat window language for the particular group.
agents list contains all members of the particular group. The group with id 0 doesn't return the agents list because it always contains all agents from the license and it cannot be modified.

GET /groups

Copied!

curl "https://api.livechatinc.com/groups" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

[
  {
    "id": 0,
    "name": "All operators",
    "language": "en",
    "status": "accepting chats"
  },
  {
    "id": 1,
    "name": "Invoicing",
    "language": "en",
    "agents": ["jane.doe@mycompany.com"],
    "status": "offline"
  },
  {
    "id": 2,
    "name": "Sales",
    "language": "en",
    "agents": ["john.doe@mycompany.com", "jenny.doe@mycompany.com"],
    "status": "not accepting chats"
  },
  {
    "id": 3,
    "name": "Technical Support",
    "language": "en",
    "agents": ["john.doe@mycompany.com"],
    "status": "accepting chats"
  }
]

Get a single group details

Returns group details for the given GROUP_ID.

Required scopes

groups--all:ro

Or, groups_read if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Parameters

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

accepting chats – when at least one agent from the group is logged in and has the accepting chats status.
not accepting chats – when at least one agent from the group is logged in but has the not accepting chats status.
offline – when all agents from the group are offline.

GET /groups/<GROUP_ID>

Copied!

curl "https://api.livechatinc.com/groups/2" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

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

Create a new group

Creates a new group in your license.

Required scopes

groups--all:rw

Or, groups_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Required parameters

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

Optional parameters

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

POST /groups

Copied!

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

Response

Copied!

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

Update a group

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

Required scopes

groups--all:rw

Or, groups_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

Optional parameters

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

PUT /groups/<GROUP_ID>

Copied!

curl "https://api.livechatinc.com/groups/3" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 -X PUT \
  -H Content-type:application/json \
  -d '{
        "name": "Quality Assurance",
        "agents": [
          "john.doe@mycompany.com",
          "jane.doe@mycompany.com"
        ]
      }'

Response

Copied!

{
  "id": 3,
  "name": "Quality Assurance",
  "language": "en",
  "agents": ["john.doe@mycompany.com", "jane.doe@mycompany.com"],
  "status": "offline"
}

Remove a group

Removes a group with the given GROUP_ID.

Required scopes

groups--all:rw

Or, groups_write if you use the old LiveChat protocol.

💡 Not sure which protocol you use? You use the old one if you don't see the new scopes in Developer Console.

DELETE /groups/<GROUP_ID>

Copied!

curl "https://api.livechatinc.com/groups/4" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

{
  "result": "group removed successfully"
}

Status

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

Available paths

Methods	Path
`GET`	`/status`

Get status

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

Optional parameters

Parameter	Description
`group`	defaults to 0

GET /status

Copied!

curl "https://api.livechatinc.com/status/1" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "status": "online"
}

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

Parameter	Description
`group`	returns tags from chosen group

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

Parameter	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/<TICKET_ID>`
`POST`	`/tickets`
`PUT`	`/tickets/<TICKET_ID>/tags`

Get list of tickets

Returns all tickets.

Required scopes

tickets_read

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 indicates the total number of pages.

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

GET /tickets

Copied!

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

Response

Copied!

{
  "pages": 1,
  "total": 15,
  "tickets": [
    {
      "assignee": {
        "id": "jane.doe@mycompany.com",
        "name": "Jane Doe"
      },
      "events": [
        {
          "author": {
            "id": "mary.brown@email.com",
            "name": "Mary Brown",
            "type": "client"
          },
          "date": 1384554260,
          "is_private": false,
          "message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
          "type": "message",
          "source": {
            "type": "mail"
          }
        },
        {
          "to": {
            "id": "jane.doe@mycompany.com",
            "name": "Jane Doe"
          },
          "author": {
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554270,
          "type": "assignee_changed"
        },
        {
          "message": "Jane, could you please find a moment to handle this customer's complaint?",
          "is_private": true,
          "author": {
            "type": "agent",
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554322,
          "type": "message",
          "source": {
            "type": "lc2"
          }
        }
      ],
      "id": "5FUED",
      "requester": {
        "mail": "mary.brown@email.com",
        "name": "Mary Brown"
      },
      "groups": [0],
      "status": "open",
      "subject": "My new shoes are broken",
      "modified": 1384790802,
      "source": {
        "type": "mail"
      },
      "opened": [
        {
          "from": 1384554260
        }
      ],
      "firstResponse": {},
      "tags": ["sales", "support", "feedback"]
    }
    // ...
  ]
}

Get single ticket

Returns a single ticket item for the given TICKET_ID.

Required scopes

tickets_read

GET /tickets/<TICKET_ID>

Copied!

curl "https://api.livechatinc.com/tickets/5FUED" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "pages": 1,
  "total": 15,
  "tickets": [
    {
      "assignee": {
        "id": "jane.doe@mycompany.com",
        "name": "Jane Doe"
      },
      "events": [
        {
          "author": {
            "id": "mary.brown@email.com",
            "name": "Mary Brown",
            "type": "client"
          },
          "date": 1384554260,
          "is_private": false,
          "message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
          "type": "message",
          "source": {
            "type": "mail"
          }
        },
        {
          "to": {
            "id": "jane.doe@mycompany.com",
            "name": "Jane Doe"
          },
          "author": {
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554270,
          "type": "assignee_changed"
        },
        {
          "message": "Jane, could you please find a moment to handle this customer's complaint?",
          "is_private": true,
          "author": {
            "type": "agent",
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554322,
          "type": "message",
          "source": {
            "type": "lc2"
          }
        }
      ],
      "id": "5FUED",
      "requester": {
        "mail": "mary.brown@email.com",
        "name": "Mary Brown"
      },
      "groups": [0],
      "status": "open",
      "subject": "My new shoes are broken",
      "modified": 1384790802,
      "source": {
        "type": "mail"
      },
      "opened": [
        {
          "from": 1384554260
        }
      ],
      "firstResponse": {},
      "tags": ["sales", "support", "feedback"]
    }
    // ...
  ]
}

Create a ticket

Creates a new ticket.

Required scopes

tickets_write

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]`

POST /tickets

Copied!

curl "https://api.livechatinc.com/tickets" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -H Content-type:application/json \
  -d '{
      "subject":"I have a problem",
      "message":"Hi,I have a problem with my shoes. Could you please advise?",
      "requester":
      {
        "mail":"mary.brown@email.com",
        "name":"Mary Brown"
      }
     }'

Response

Copied!

{
  "pages": 1,
  "total": 15,
  "tickets": [
    {
      "assignee": {
        "id": "jane.doe@mycompany.com",
        "name": "Jane Doe"
      },
      "events": [
        {
          "author": {
            "id": "mary.brown@email.com",
            "name": "Mary Brown",
            "type": "client"
          },
          "date": 1384554260,
          "is_private": false,
          "message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
          "type": "message",
          "source": {
            "type": "mail"
          }
        },
        {
          "to": {
            "id": "jane.doe@mycompany.com",
            "name": "Jane Doe"
          },
          "author": {
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554270,
          "type": "assignee_changed"
        },
        {
          "message": "Jane, could you please find a moment to handle this customer's complaint?",
          "is_private": true,
          "author": {
            "type": "agent",
            "id": "john.doe@mycompany.com",
            "name": "John Doe"
          },
          "date": 1384554322,
          "type": "message",
          "source": {
            "type": "lc2"
          }
        }
      ],
      "id": "5FUED",
      "requester": {
        "mail": "mary.brown@email.com",
        "name": "Mary Brown"
      },
      "groups": [0],
      "status": "open",
      "subject": "My new shoes are broken",
      "modified": 1384790802,
      "source": {
        "type": "mail"
      },
      "opened": [
        {
          "from": 1384554260
        }
      ],
      "firstResponse": {},
      "tags": ["sales", "support", "feedback"]
    }
    // ...
  ]
}

Update ticket tags

Updates tags associated with the ticket.

Required scopes

tickets_write

Required parameters

Parameter	Description
`tag`	array of used tags

PUT /tickets/<TICKET_ID>/tags

Copied!

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

Response

Copied!

{
  "pages": 1,
  "total": 15,
  "tickets": [
  {
    "assignee": {
      "id": "jane.doe@mycompany.com",
      "name": "Jane Doe"
    },
    "events": [
    {
      "author": {
        "id": "mary.brown@email.com",
        "name": "Mary Brown",
        "type": "client"
      },
      "date": 1384554260,
      "is_private": false,
      "message": "Hello,\n\nIt seems that my new shoes are broken. What can we do about this?",
      "type": "message",
      "source": {
        "type": "mail"
      }
    }, {
      "to": {
        "id": "jane.doe@mycompany.com",
        "name": "Jane Doe"
      },
      "author": {
        "id": "john.doe@mycompany.com",
        "name": "John Doe"
      },
      "date": 1384554270,
      "type": "assignee_changed"
    }, {
      "message": "Jane, could you please find a moment to handle this customer's complaint?",
      "is_private": true,
      "author": {
        "type": "agent",
        "id": "john.doe@mycompany.com",
        "name": "John Doe"
      },
      "date": 1384554322,
      "type": "message",
      "source": {
        "type": "lc2"
      }
    }],
    "id": "5FUED",
    "requester": {
      "mail": "mary.brown@email.com",
      "name": "Mary Brown"
    },
    "groups": [0],
    "status": "open",
    "subject": "My new shoes are broken",
    "modified": 1384790802,
    "source": {
      "type": "mail"
    },
    "opened": [{
      "from": 1384554260
    }],
    "firstResponse": {}
  },
  "tags": [
    "sales",
    "support",
    "feedback"
  ],
  // ...
  ]
}

Webhooks (deprecated)

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

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

When your server receives a webhook from LiveChat, it should respond with HTTP 200 response. Otherwise, LiveChat will retry sending the webhook to your service a number of times until it receives the correct HTTP 200 response.

The timeout is set to ~10 seconds. If we don't receive HTTP 200 response within that time period, we'll retry sending the webhook up to 10 times within 6 hours.

If your endpoint is responsible for both receiving data from our webhook and making further actions, like creating a record in a database, then the whole process may take longer than 10 seconds. In such a case, we believe, the best solution would be to split your mechanism into 2 separate actions:

1) Retrieving data from the LiveChat webhook (sending HTTP 200 back to us immediately).

2) Further processing of the data and passing it to other services.

That would prevent situations in which the process takes longer than our webhook timeout and data isn't pushed from our side again.

Display configured webhooks

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.

Required scopes

webhooks_manage

GET /webhooks

Copied!

curl "https://api.livechatinc.com/webhooks" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2

Response

Copied!

{
  "events": [
    {
      "licence": 12345,
      "event_type": "chat_started",
      "data_types": ["chat", "visitor"],
      "url": "https://my-company.com/parse_webhook.php",
      "verified": true,
      "token": "0adec158e423091d5a36c9fce95775db",
      "id": "39612eee5f1b431217aafb9de19c1e32"
    }
  ]
}

Create a new webhook

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

Creates a new webhook.

Required scopes

webhooks_manage

Required parameters

Parameter	Description
`event_type`	must be one of `chat_started`, `chat_ended`, `chat_changed`, `visitor_queued`, `ticket_created` or `canned_response_changed`
`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:

Parameter	Description
`chat_started`	when the chat is started
`chat_ended`	when the chat is ended
`chat_changed`	when the chat is tagged
`visitor_queued`	when the visitor enters the queue before a chat
`ticket_created`	when a new ticket is created
`canned_response_changed`	when a canned response is created, modified or deleted

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

Parameter	Description
`chat`	only supported in `chat_started`, `chat_changed` and `chat_ended` event types
`visitor`	only supported in `chat_started`, `chat_ended`, `chat_changed` 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
`canned_response`	only supported in `canned_response_changed` event type

POST /webhooks

Copied!

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

Response

Copied!

{
  "events": [
    {
      "licence": 12345,
      "event_type": "chat_started",
      "data_types": ["chat", "visitor"],
      "url": "https://my-company.com/parse_webhook.php",
      "verified": true,
      "token": "0adec158e423091d5a36c9fce95775db",
      "id": "39612eee5f1b431217aafb9de19c1e32"
    }
  ]
}

Delete a webhook

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

Deletes a webhook with the given ID.

Required scopes

webhooks_manage

DELETE /webhooks/<ID>

Copied!

curl "https://api.livechatinc.com/webhooks/39612eee5(...)" \
  -H "Authorization: Basic john.doe@mycompany.com:<your_PAT>" \ \
  -H X-API-Version:2 \
  -X DELETE

Response

Copied!

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

Visitors

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

Available paths

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

List all visitors

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

Required scopes

visitors_read

Optional parameters

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:

browsing
chatting
logging into chat
queued
invited
refused invitation
chat closed

The possible state filter values are chatting and queued.

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

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

GET /visitors

Copied!

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

Response

Copied!

[
  {
    "browser": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
    "chat": {
      // (...)
    },
    "chat_id": "DL1G0UED4H",
    "chat_start_time": "2017-02-16 12:54:26",
    "chat_start_time_ts": 1487246066,
    "chats": 1,
    "custom_variables": [
      {
        "key": "empty_cart",
        "value": "true"
      }
    ],
    "city": "Greenville",
    "country": "United States",
    "country_code": "US",
    "greetings_accepted": 1,
    "greetings_all": 2,
    "greetings_refused": 1,
    "group": 102,
    "host": "very-hosty.sl.us",
    "id": "S148dea44981.d9443253fef2",
    "invitation": "",
    "ip": "8.8.8.8",
    "language": "en",
    "last_visit": "2017-02-16 12:36:21",
    "last_visit_ts": 1487244981,
    "latitude": "35.6127",
    "longitude": "-77.3663",
    "name": "Visitor",
    "operators": [
      // (...)
    ],
    "page_address": "https://developers.livechat.com/docs/extending-chat-widget/javascript-api/",
    "page_current": "https://developers.livechat.com/docs/extending-chat-widget/javascript-api/",
    "page_entered": "2017-02-16 12:36:21",
    "page_entered_ts": 1487244981,
    "page_time": "2017-02-16 12:39:12",
    "page_time_ts": 1487245152,
    "page_title": "LiveChat – Chat Window API (JS)",
    "page_views": 16,
    "prechat_survey": [
      // (...)
    ],
    "queue_start_time": 46843480,
    "referrer": "https://www.livechat.com/",
    "region": "North Carolina",
    "state": "chatting",
    "timezone": "America/New_York",
    "visit_path": [
      {
        "invitation": "Time on site: 30 sec",
        "page": "https://developers.livechat.com/docs/",
        "time": "2017-02-16 12:36:21",
        "time_ref": 1487244981,
        "time_ts": 1487244981,
        "title": "LiveChat Developers - REST API & Integrations"
      },
      {
        "invitation": "",
        "page": "https://developers.livechat.com/docs/",
        "time": "2017-02-16 12:38:33",
        "time_ref": 1487245113,
        "time_ts": 1487245113,
        "title": "LiveChat Platform Docs"
      }
      // (...)
    ],
    "visits": 3
  }
  // (...)
]

Configuration API.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

Configuration API