REST API

Introduction

Welcome to the LiveChat API documentation! Our API provides flexible tools that can be used in the creation of new, outstanding projects. Each time we see creative development by skilled engineers we smile a bit more!

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

Basic API usage

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

The next segment of the URI path depends on the type of request. For example:

https://api.livechatinc.com/agents

to get or modify agents data.

All requests must have X-API-VERSION header set to number of the version that you'd like to use. The most recent version is 2.

Example method call

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

Authentication

You must use your login and API_KEY for each method call.

You'll find your API_KEY in your LiveChat profile.

Authentication to the API occurs via HTTP Basic Auth. Provide your login as the basic auth username and the API_KEY as the password. You must authenticate for all requests.

All API requests must be made over HTTPS.

For example, if your login is john.doe@mycompany.com, your API key is c14b85863755158d7aa5cc4ba17f61cb and you want to invoke the agents API method, your request will look like:

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

Data format

LiveChat API returns data in JSON format. Example agents list returned in this format:

Data format

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

JSONP

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

Example JSONP request

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

Example JSONP response

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

Error handling

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

HTTP status codes summary

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

LiveChat API libraries

Agents

Use this integration to manage your agents. This function can also be used to get information regarding your agents.

Available paths

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

Path

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

Example request

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

Example response

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

Get a single agent details

Return complete details of the agent for the given LOGIN.

Attributes:

  • login – the agent's e-mail address.
  • name – the agent's name.
  • login_status – possible values: accepting chats, not accepting chats, offline.
  • permission – possible values: owner, administrator, normal.
  • daily_summary – whether or not the agent receive daily summary.
  • job_title – defaults to: Support Agent.
  • avatar – path to the image on Amazon s3.
  • notifications – whether or not the specific notification is enabled.
  • max_chats_count – limit of the concurrent chats.
  • groups[] – list of groups the agent is a member of.
  • status – possible values: accepting chats, not accepting chats, offline.
  • last_logout – timestamp of the agent's last logout.
  • api_key – the agent's API key.

Path

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

Example request

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

Example response

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

Create a new agent

Creates a new agent in your license.

Required properties:

  • login – must be correct e-mail address.
  • name

Optional properties:

  • job_title – defaults to: Support Agent.
  • login_status – possible values: accepting chats (default), not accepting chats.
  • password – the minimum length is 5 (if not provided, an email with the activation link will be sent).
  • permissionadministrator, normal (default).
  • groups[] – list of group IDs.
  • notifications – object (allowed keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, new_goal, allowed values: 0 or 1).
  • daily_summary0 or 1 (default).
  • max_chats_count – defaults to 6.

Path

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

Example request

curl "https://api.livechatinc.com/agents" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "login=jenny.doe@mycompany.com&\
      name=Jenny+Doe&\
      permission=administrator&\
      groups[]=1&\
      groups[]=2&\
      notifications["new_visitor"]=1&\
      notifications["new_goal"]=1"

Example JSON request

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

Example response

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

Update an agent

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

All properties are optional:

  • job_title
  • name
  • login_statusaccepting chats (default), not accepting chats.
  • password – the minimum length is 5.
  • current_password – required when setting a new password
  • permissionadministrator, normal (default).
  • statusaccepting chats, not accepting chats, offline.
  • groups[] – list of group IDs.
  • notifications – object (allowed keys: new_visitor, returning_visitor, queued_visitor, visitor_is_typing, new_goal, allowed values: 0 or 1).
  • daily_summary0 or 1.
  • max_chats_count
  • work_scheduler – available only for enterprise plan. Object with allowed keys: days of the week, e.g. monday. For each day of the week valid keys are start, end or enabled. It is possible to pass all work scheduler keys at once. start and end should be passed is 24h-hour clock format. enable allowed values are 1 or 0.

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

  • password
  • name
  • job_title
  • daily_summary
  • notifications
  • login_status
  • status

Path

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

Example request

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

Example JSON request

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

Example response

{
  "login": "jenny.doe@mycompany.com",
  "name": "Jenny Doe",
  "login_status": "not accepting chats",
  "permission": "administrator",
  "daily_summary": 1,
  "job_title": "Support Agent",
  "avatar": "livechat.s3.amazonaws.com/default/avatars/45bcb5f592dbf5aac8f88dcfd6bc937c.png",
  "notifications": {
    "new_visitor": 1,
    "returning_visitor": 1,
    "queued_visitor": 1,
    "visitor_is_typing": 0,
    "new_goal": 1
  },
  "max_chats_count": 2,
  "work_scheduler":{
    "sunday":{
      "enabled":0,
      "start":"11:00",
      "end":"17:00"
    },
    "monday":{
      "enabled":1,
      "start":"09:00",
      "end":"17:00"
    },
    "tuesday":{
      "enabled":1,
      "start":"09:00",
      "end":"17:00"
    },
    "wednesday":{
      "enabled":1,
      "start":"09:00",
      "end":"17:00"
    },
    "thursday":{
      "enabled":1,
      "start":"09:00",
      "end":"17:00"
    },
    "friday":{
      "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

Reset API key for the agent with given LOGIN.

Path

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

Example request

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

Example response

Return format is the same as in update agent method.
    

Remove an agent

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

Path

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

Example request

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

Example response

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

Canned responses

This function allows you to get a full list of your canned responses and change them.

Available paths

[GET|POST]       /canned_responses
[GET|PUT|DELETE] /canned_responses/<CANNED_RESPONSE_ID>

List all canned responses

Returns list of all currently set canned responses.

Optional parameter:

  • group – defaults to 0.

Additional info:

If the canned response was modified, it has additional modification_date and modified_by parameters.

Path

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

Example request

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

Example response

[
  {
    "id": 3151,
    "group": 1,
    "text": "Can I help you with anything else?",
    "creation_date": 1358257181,
    "created_by": "john.doe@mycompany.com",
    "tags": [
      "help",
      "else"
    ]
  },
  {
    "id": 3161,
    "group": 1,
    "text": "What product are you interested in?",
    "creation_date": 1358257229,
    "created_by": "john.doe@mycompany.com",
    "modification_date": 1358864338,
    "modified_by": "jenny.doe@mycompany.com",
    "tags": [
      "product",
      "interest"
    ]
  },
  {
      "id": 3171,
      "group": 1,
      "text": "I will transfer you to the agent responsible for this matter.",
      "creation_date": 1358864376,
      "created_by": "jenny.doe@mycompany.com",
      "tags": [
        "transfer",
        "matter"
      ]
    }
]
		

Get single canned response

CANNED_RESPONSE_ID is obtained from the all canned responses list.

Attributes:

  • id – id of the canned response.
  • group – id of the group that canned response is assigned to.
  • text – canned response text.
  • creation_date – creation date timestamp.
  • created_by – login of the canned response's author.
  • tags – an array of canned response's tags.

Path

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

Example request

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

Example response

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

Create a new canned response

Creates a new canned response.

Required parameters:

  • text – response text.
  • tags – array of strings (tags)

Optional properties:

  • group – defaults to 0.

Path

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

Example request

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

Example JSON request

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

Example response

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

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

  • text – response text.
  • tags – array of strings (tags).

Path

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

Example request

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

Example JSON request

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

Example response

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

Remove a canned response

Removes a canned response with the given CANNED_RESPONSE_ID.

Path

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

Example request

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

Example response

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

Chats

Get finished chats and left messages by using the "type" parameter of this function. Additionally, you can also use it to send chat transcripts.

Available paths

[GET]  /chats
[GET]  /chats/<CHAT_ID>
[POST] /chats/<CHAT_ID>/send_transcript
[PUT] /chats/<CHAT_ID>/tags

Get list of chats

Returns all ended chats.

Optional parameters:

  • date_fromYYYY-MM-DD. Defaults to the beginning of time.
  • date_toYYYY-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_goal1/0. If 1 is passed, returns chats having any goal.
  • queued1/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_pending1/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.

Additional info:

  • goal parameter will appear only if a goal for a particular chat has been reached.
  • referrer parameter will appear only if referrer url exists.
  • custom_variables parameter will be available only if the custom variables are defined in the tracking code.
  • integration_variables parameter will appear only if a visitor logs in with Facebook.
  • queue parameter will appear only if chat started from queue.
  • duration is counted in seconds.
  • total tells you the total number of chats.
  • pages tells you the total number of pages.

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.

Path

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

Example request

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

Example response

{
   "chats":[
      {
         "type":"chat",
         "id":"MH022RD0K5",
         "visitor":{
            "id":"S1355415390.49b8940793",
            "name":"Mary Brown",
            "ip":"85.10.5.156"
         },
         "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.name",
               "value":"Mary Brown"
            },
            {
               "key":"facebook.first_name",
               "value":"Mary"
            },
            {
               "key":"facebook.last_name",
               "value":"Brown"
            },
            {
               "key":"facebook.gender",
               "value":"female"
            },
            {
               "key":"facebook.locale",
               "value":"en_US"
            },
            {
               "key":"facebook.link",
               "value":"http://www.facebook.com/mary.brown"
            },
            {
               "key":"facebook.username",
               "value":"mary.brown"
            },
            {
               "key":"facebook.email",
               "value":"mary.brown@email.com"
            }
         ],
         "goals":[
            {
               "id":71,
               "name":"goal_name",
               "order":{
                  "id":"ABC",
                  "description":"product one",
                  "price":"199",
                  "currency":"CZK"
               }
            },
            {
               "id":72,
               "name":"goal_name",
               "order":{

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

Get single chat

Returns single chat item for the given CHAT_ID.

Path

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

Example request

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

Example response

Return format is the same as the single chat item in chats list.

Send chat transcript to e-mail

Required parameter:
  • to – receiver's email address.

Path

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

Example request

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

Example JSON request

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

Example response

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

Update chat tags

Required parameter:
  • tag – array of used tags.

Path

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

Example request

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

Example JSON request

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

Example response

{
   "chats":[
      {
         "type":"chat",
         "id":"MH022RD0K5",
         "visitor":{
            "id":"S1355415390.49b8940793",
            "name":"Mary Brown",
            "ip":"85.10.5.156"
         },
         "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.name",
               "value":"Mary Brown"
            },
            {
               "key":"facebook.first_name",
               "value":"Mary"
            },
            {
               "key":"facebook.last_name",
               "value":"Brown"
            },
            {
               "key":"facebook.gender",
               "value":"female"
            },
            {
               "key":"facebook.locale",
               "value":"en_US"
            },
            {
               "key":"facebook.link",
               "value":"http://www.facebook.com/mary.brown"
            },
            {
               "key":"facebook.username",
               "value":"mary.brown"
            },
            {
               "key":"facebook.email",
               "value":"mary.brown@email.com"
            }
         ],
         "goals":[
            {
               "id":71,
               "name":"goal_name",
               "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"
            },
            {
               "author_name":"Mary Brown",
               "text":"How are you?",
               "date":"Wed, 01/23/13 11:41:01 am",
               "timestamp":1358937661,
               "user_type":"visitor"
            },
            {
               "author_name":"John Doe",
               "text":"Thanks, fine :)",
               "date":"Wed, 01/23/13 11:41:05 am",
               "timestamp":1358937665,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com"
            },
            {
               "author_name":"Jane Doe",
               "text":"Message from supervisor.",
               "date":"Wed, 01/23/13 11:57:13 am",
               "timestamp":1358938633,
               "user_type":"supervisor",
               "agent_id":"jane.doe@mycompany.com"
            }
         ],
         "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"
            },
            {
               "author_name":"Mary Brown",
               "text":"How are you?",
               "date":"Wed, 01/23/13 11:41:01 am",
               "timestamp":1358937661,
               "user_type":"visitor",
               "type":"message"
            },
            {
               "text":"Mary Brown uploaded the attachment.",
               "date":"Wed, 01/23/13 11:41:02 am",
               "timestamp":1358937662,
               "type":"attachment",
               "user_type":"visitor",
               "files":[
                  "https://static.livechatinc.com/.../hello.JPG"
               ],
               "author_name":"Mary Brown"
            },
            {
               "author_name":"John Doe",
               "text":"Thanks, fine :)",
               "date":"Wed, 01/23/13 11:41:05 am",
               "timestamp":1358937665,
               "user_type":"agent",
               "agent_id":"john.doe@mycompany.com",
               "type":"message"
            },
            {
               "author_name":"Jane Doe",
               "text":"Message from supervisor.",
               "date":"Wed, 01/23/13 11:57:13 am",
               "timestamp":1358938633,
               "user_type":"supervisor",
               "agent_id":"jane.doe@mycompany.com",
               "type":"message"
            },
            {
               "text":"Mary Brown closed the chat.",
               "date":"Wed, 01/23/13 11:57:14 am",
               "timestamp":1358937663,
               "type":"event",
               "user_type":"visitor"
            },
         ],
         "started_timestamp":1358937653,
         "ended_timestamp":1358939109,
         "ended":"Wed, 01/23/13 12:05:09 pm"
      },
      {
         "...":"..."
      }
   ],
   "total":2,
   "pages":1
}

Goals

Pull information regarding your goals and manage them using this function.

Available paths

[GET|POST]       /goals
[GET|PUT|DELETE] /goals/<GOAL_ID>
[POST]           /goals/<GOAL_ID>/mark_as_successful

List all goals

Returns all currently set goals.

Additional info:

  • active tells you if the particular goal is enabled or not.

Path

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

Example request

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

Example response

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

Get a single goal details

Returns goal details for the given GOAL_ID.

Attributes:

  • id – id of the goal.
  • name – goal name.
  • active – whether or not the goal is enabled.
  • type – type of the goal.

Additional info:

type can take the following values:

  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value.
  • url – with two additional parameters: url and match_type with possible values: substring (default), exact.
  • api – without any additional parameters.

Path

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

Example request

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

Example response

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

Mark goal as successful

GOAL_ID is obtained from the goals list.

Required parameter:

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

  • order_id – for example: ''AP723HVCA721''
  • order_description – for example: ''Nike shoes''
  • order_price – for example: ''199.00'', only the period is allowed as a separation character
  • order_currency – for example: ''USD''

Path

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

Example request

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

Example JSON request

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

Example response

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

Add a new goal

Creates new goal.

Required parameters:

  • name
  • type

Additional info:

type can take the following values:
  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value. Both are required.
  • url – with two additional parameters: url (required) and match_type (optional) with possible values: substring (default), exact.
  • api – without any additional parameters.

active parameter tells you if the goal is active or not.

Path

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

Example request

curl "https://api.livechatinc.com/goals" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-VERSION:2 \
  -d "name=new%20goal&\
  type=url&\
  url=http://www.mystore.com/checkout/thank_you&\
  match_type=exact" 

Example JSON request

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

Example response

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

Update a goal

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

GOAL_ID is obtained from the goals list.

All parameters are optional:

  • name
  • type

Additional info:

type can take the following values:
  • custom_variable – with two additional parameters: custom_variable_name, custom_variable_value. Both are required.
  • url – with two additional parameters: url (required) and match_type (optional) with possible values: substring (default), exact.
  • api – without any additional parameters.

active parameter tells you if the goal is active or not.

Path

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

Example request

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

Example JSON request

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

Example response

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

Remove a goal

Removes a goal with the given GOAL_ID.

Path

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

Example request

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

Example response

{
  "result": "goal removed successfully"
}
    

Greetings

You can use this function to manage your greetings and greeting-related data.

Available paths

[GET|POST]       /greetings
[GET|PUT|DELETE] /greetings/<GREETING_ID>

List all greetings

Returns the list of all greetings.

Optional properties:

  • group – Group number can be specified to get greetings from a given group. If not specified, all greetings will be returned.

Path

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

Example request

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

Example response

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

Get a single greeting

Returns the specified greeting.

Additional info:

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

Path

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

Example request

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

Example result

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

Create a new greeting

Use this function to create a new greeting.

Required properties:

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

Optional properties:

  • group – creates a greeting displayed in particular group only. Defaults to 0.

Path

[POST] /greetings

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

  • visit_time_site – Displays the greeting after visitor spent a certain amount of time on site.
  • visit_time_page – Displays the greeting after visitor spent a certain amount of time on page.
  • url_current – Displays the greeting for visitors on specific pages.
  • url_visited – Displays the greeting when visitor visited specific pages.
  • pages_view_number – Displays the greeting for visitors who have seen the page for a number of times.
  • url_referrer – Displays the greeting when the visitor arrived from a referring page.
  • geolocation – Displays the greeting for visitors from specific countries or cities.
  • visits_number – Displays the greeting for returning visitors.
  • search_keyword – Displays the greeting when visitor looked up a search keyword.

Example request

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

Example JSON request

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

Example result

{
  "id": 2451,
  "active": true,
  "name": "my custom invitation",
  "rules": [
    {
      "id": 8241,
      "value": "2",
      "type": "visits_number",
      "operator": "greater_or_equal",
      "condition": "and"
    },
    {
      "id": 8251,
      "value": "15",
      "type": "visit_time_page",
      "operator": "greater_than",
      "condition": "and"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}
  • custom_variable – The greeting will be sent when the specified variable is met.

Note: when using the custom_variable greeting rule, you also need to provide variable_name and variable_value. You also can add the optional operator parameter (defaults to equals).

Example request

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

Example JSON request

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

Example result

{
  "id": 2431,
  "active": true,
  "name": "custom variable type greeting",
  "rules": [
    {
      "id": 8221,
      "type": "custom_variable",
      "operator": "contains",
      "condition": "and",
      "variable_name": "my_custom_var",
      "variable_value": "var_value"
    }
  ],
  "properties": {
    "active": "1",
    "greeting-message_text": "Hello, would you like to talk about our products?"
  }
}
  • url_funnel – Visitors who visit the specified sequence of websites will receive the greeting.

Note: when using the url_funnel greeting rule, you need to provide the urls variable. It is an array of objects with the required url parameter and optional operator parameter (defaults to: equals).

Example request

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

Example JSON request

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

Example result

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

Greetings with mutliple rules

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

Example request

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

Example JSON request

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

Example result

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

Update a greeting

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

Path

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

Update greeting name or message

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

Example request

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

Activate and deactivate greetings

Activate or deactivate a greeting using this request.

Example request

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

Change greetings rules

Change the rules of your greetings with this request.

Example request

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

Example result

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

Remove a greeting

Removes an greeting.

Path

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

Example request

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

Example response

{
  "ok": true
}

Groups

Manage your groups and group-related data using this function.

Available paths

[GET|POST]       /groups
[GET|PUT|DELETE] /groups/<GROUP_ID>

List all groups

Returns all created groups.

Additional info:

language tells you the chat window language for the particular skill. See the list of supported languages.
agents list contains all members of the particular group. Group with id 0 doesn't return agents list because it always contains all agents from the license and it cannot be modified.

Path

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

Example request

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

Example response

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

Get a single group details

Returns group details for the given GROUP_ID.

Attributes:

  • id – id of the group.
  • name – group name.
  • language – group language (defaults to English). See the list of supported languages.
  • agents – an array of group members' logins.
  • status – current status of the group.

Additional info:

status can take the following values:

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

Path

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

Example request

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

Example response

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

Create a new group

Creates a new group in your license.

Required properties:

  • name – group name.
  • agents – an array of LiveChat users' logins (e-mails).

Optional properties:

Path

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

Example request

curl "https://api.livechatinc.com/groups" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -d "name=Human+Resources&\
      agents[0]=jenny.doe@mycompany.com&\
      agents[1]=john.doe@mycompany.com" 

Example JSON request

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

Example response

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

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:

Path

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

Example request

curl "https://api.livechatinc.com/groups/3" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2 \
  -X PUT \
  -d "name=Quality+Assurance&\
      agents[0]=john.doe@mycompany.com&\
      agents[1]=jane.doe@mycompany.com" 

Example JSON request

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

Example response

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

Remove a group

Removes a group with the given GROUP_ID.

Path

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

Example request

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

Example response

{
  "result": "group removed successfully"
}
    

Reports

Pull various metrics and reporting data using this function.

Available paths

[GET] /reports/chats/total_chats
[GET] /reports/chats/source
[GET] /reports/chats/ratings
[GET] /reports/chats/ratings/ranking
[GET] /reports/chats/queued_visitors
[GET] /reports/chats/queued_visitors/waiting_times
[GET] /reports/availability
[GET] /reports/chats/goals
[GET] /reports/chats/greetings

Total chats

Shows how many chats occurred during the specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

Chat sources

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

Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.
  • tag - array of tags.

Path

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

Example request

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

Example response

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

Chat ratings report

Shows how many chats were rated and how they have been rated during specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

Chat Ranking

Shows the ratio of good to bad ratings for each operator. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.

Path

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

Example request

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

Example response

{
  "ranking": [
    {
      "good": 2502,
      "bad": 426,
      "total": 2928,
      "score": 0.8361489669658251,
      "name": "john.doe@mycompany.com"
    },
    {
      "good": 2164,
      "bad": 443,
      "total": 2607,
      "score": 0.8094273999034496,
      "name": "jane.doe@mycompany.com"
    },
    {
      "good": 1070,
      "bad": 215,
      "total": 1285,
      "score": 0.8029689181922964,
      "name": "jenny.doe@mycompany.com"
    }
}

Queued visitors

Shows how many visitors were waiting in the queue, how many abandoned the queue or proceeded to chats. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

{
  "2013-01-29": {
    "queued": {
      "count": 6,
    },
    "left_queue": {
      "count": 3,
    },
    "entered_chat": {
      "count": 3,
    }
  },
  "2013-01-30": {
    "queued": {
      "count": 2,
    },
    "left_queue": {
      "count": 0
    },
    "entered_chat": {
      "count": 2,
    }
  }
}

Queue waiting times

Shows Minimum, Average and Maximum waiting time. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

Availability

Shows how much the agent (or group or whole account) was available for chatting during specified period. When querying for one day results are shown in minutes per every hour, otherwise in hours for each day. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
Results are grouped by hours when querying for single day, grouped by days otherwise.

Path

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

Example request

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

Example response

{
  "2013-01-25": {
    "hours": 0
  },
  "2013-01-26": {
    "hours": 0
  },
  "2013-01-27": {
    "hours": 0.01
  },
  "2013-01-28": {
    "hours": 7.85
  },
  "2013-01-29": {
    "hours": 7.99
  },
  "2013-01-30": {
    "hours": 2.28
  }
}

Chatting time

Shows how much time the agent (or group) spent on chatting during specified period. When querying for one day results are shown in minutes per every hour, otherwise in hours for each day. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, returns statistics for the specified agent

Path

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

Example request

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

Example response

{
  "2013-01-25": {
    "hours": 8.17
  },
  "2013-01-26": {
    "hours": 9.2
  },
  "2013-01-27": {
    "hours": 5.3
  },
  "2013-01-28": {
    "hours": 7.16
  },
  "2013-01-29": {
    "hours": 10.71
  },
  "2013-01-30": {
    "hours": 6.51
  }
}

Goals

Shows the number of reached goals. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • goal – id of the goal, not set by default.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

New tickets

Shows the number of the tickets created during the specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

Tickets' first response time

Shows the time of the first response to tickets that were responded to for the first time during the specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.
The following parameters are returned for each date:
  • count – the number of tickets that were responded to for the first time that day.
  • hours – average first response time of the tickets. For example, "hours": 0.83 means an average first response time of 49mins 48sec.

Path

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

Example request

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

Example response

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

Solved tickets

Shows the number of the tickets solved during the specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.

Path

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

Example request

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

Example response

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

Tickets' resolution time

Shows the resolution time of the tickets that were solved during the specified period. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • agent – agent's login, not set by default, return statistics for the specified agent.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.
Two parameters are returned:
  • count – the number of tickets that were responded to for the first time that day.
  • hours – average first response time of the tickets. For example, "hours": 0.83 means an average first response time of 49mins 48sec.

Path

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

Example request

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

Example response

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

Ticket sources

Shows the distribution of tickets between various channels. Optional arguments:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • group – id of the group, not set by default, returns statistics for the specified group.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.
The following parameters are returned for each date:
  • tickets_from_chat_window – the number of tickets created by the visitor via the ticket form,
  • tickets_from_mail – the number of tickets created by sending an email to your support email tied to LiveChat,
  • tickets_from_chat – the number of tickets created by the agents during a chat.

Path

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

Example request

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

Example response

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

Greetings conversions

Returns the “greetings to chats to goals” conversion rates report. displayed is the number of displayed greetings. accepted tells you how many chats resulted from these greetings. goals tells you how many goals resulted from these greetings. Optional properties:
  • date_fromYYYY-MM-DD, defaults to the beginning of time.
  • date_toYYYY-MM-DD, defaults to today.
  • timezone – timezone in the TZ format (e.g. America/Phoenix).
  • greeting – id of the greeting, not set by default, returns statistics for the specified greeting.
  • group – id of the group, not set by default, returns statistics for the specified group.
  • group_by – defaults to day (or hour when date_from equals date_to), can be set to month, hour or day.
  • goal – id of the goal, not set by default, returns goals statistics for the specified goal.

Path

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

Example request

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

Example response

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

Status

This function will allow you to know the current status of your live chat.

Available paths

[GET] /status

Get status

Returns current LiveChat status.

Available return values: online, offline.

Optional parameter:

  • group – defaults to 0.

Path

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

Example request

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

Example response

{
  "status":"online"
}

Tags

Manage your tags.

Available paths

[GET|POST]  /tags
[DELETE]   /tags/<TAG>

List all tags

Returns tags from all groups.

Optional parameter:

  • group - returns tags from chosen group.

Path

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

Example request

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

Example 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

Add new tag. Permitted for owner and admins only.

Required properties:

  • author - agent login.
  • tag - name of a tag.
  • group - id of the group that tag will be added to.

Path

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

Example request

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

Example JSON request

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

Example 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. Agents will no longer be able to tag chats and tickets using this tag. Note: deleting a tag will not remove tags from archived chats and tickets.

Required properties:

  • tag - tag name.
  • group - id of the group that tag is assigned to.

Path

[DELETE]   /tags/<TAG>

Example request

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

Example JSON request

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

Example response

{
  "ok": true
}
    

Tickets

Get all tickets and manage them using this set of API methods.

Available paths

[GET]  /tickets
[GET]  /tickets/<TICKET_ID>
[POST] /tickets
[PUT]  /tickets/<TICKET_ID>/tags

Get list of tickets

Returns all tickets.

Optional parameters:

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

Additional info:

Results are divided into pages, each containing 25 tickets.

total tells you the total number of tickets.
pages tells you the total number of pages.

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

Path

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

Example request

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

Example response

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

Get single ticket

Returns single ticket item for the given TICKET_ID.

Path

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

Example request

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

Example response

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

Create a ticket

Creates a new ticket.

Required parameters:

  • message – requester's message.
  • requester[mail] – requester's email address.

Optional parameters:

  • 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].

Path

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

Example request

curl "https://api.livechatinc.com/tickets" \
  -u john.doe@mycompany.com:c14b85863755158d7aa5cc4ba17f61cb \
  -H X-API-Version:2  \
  -X POST -d "subject=I+have+a+problem&\
  message=Hi,I+have+a+problem+with+my+shoes.+Could+you+please+advise?&\
  requester[mail]=mary.brown@email.com&\
  requester[name]=Mary+Brown"

Example JSON request

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

Example response

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

Update ticket tags

Required parameter:
  • tag – array of used tags.

Path

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

Example request

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

Example JSON request

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

Example response

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

Visitors

Use this function to get visitor-related information.

Available paths

[GET]  /visitors
[POST] /visitors/<VISITOR_ID>/details

List all visitors

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

Optional parameters:

  • state parameter determines whether the visitors are chatting or wait in the queue. It needs to have either the chatting or queued value.
  • group[] parameter decides which group will be used for the listing. Use group numbers as values to select visitors only for the specified group.
  • count parameter will allow you to return the number of visitors (when the value is set to 1) instead of all the available information (when it is set to 0). The parameter is set to 0 by default.

Additional info:

Possible state values returned without any filter are:

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

Possible state filter values are chatting and queued.

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

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

Path

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

Example request

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

Example response

[
  {
    "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_2) AppleWebKit/536.26.14 (KHTML, like Gecko) Version/6.0.1 Safari/536.26.14",
    "chat_id": "MH0H3V3XO3",
    "chat_start_time": "2013-01-31 15:51:03",
    "city": "Greenville",
    "country": "United States",
    "host": "152.27.26.254",
    "id": "S1355415390.49b8940793",
    "ip": "152.27.26.254",
    "language": "en",
    "last_visit": "2013-01-31 15:43:05",
    "latitude": "35.6127",
    "longitude": "-77.3663",
    "operators": [
      {
        "id": "john.doe@mycompany.com",
        "display_name": "John Doe"
      }
    ],
    "page_current": "http://www.mycompany.com/products/shoes",
    "page_entered": "2013-01-31 15:49:17",
    "page_time": "2013-01-31 15:49:17",
    "prechat_survey": [
      {
        "key": "Name:",
        "value": "Mark"
      },
      {
        "key": "E-mail:",
        "value": "mark.johnson@example.com"
      }
    ],
    "queue_start_time": "",
    "referrer": "",
    "region": "North Carolina",
    "state": "chatting",
    "timezone": "America/New_York",
    "custom_variables": [
      {
        "key": "empty_cart",
        "value": "true"
      }
    ],
    "chats": 27,
    "group": 0,
    "greetings_accepted": 9,
    "greetings_all": 13,
    "greetings_refused": 4,
    "visits": 16,
    "page_views": 59
  },
  {
    "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.11 (KHTML, like Gecko) Chrome/23.0.1271.101 Safari/537.11",
    "chat_id": "",
    "chat_start_time": "",
    "city": "Courbevoie",
    "country": "France",
    "host": "def92-2-87-91-13-226.dsl.sta.abo.bbox.fr",
    "id": "S1359643767.a7904dd2f2",
    "ip": "87.91.13.226",
    "language": "en",
    "last_visit": "2013-01-31 15:49:27",
    "latitude": "48.897",
    "longitude": "2.2564",
    "operators": [
      {
        "id": "",
        "display_name": ""
      }
    ],
    "page_current": "http://www.mycompany.com/",
    "page_entered": "2013-01-31 15:49:27",
    "page_time": "2013-01-31 15:49:27",
    "prechat_survey": [

    ],
    "queue_start_time": "",
    "referrer": "",
    "region": "Ile-de-France",
    "state": "online",
    "timezone": "Europe/Paris",
    "chats": 0,
    "group": 0,
    "greetings_accepted": 0,
    "greetings_all": 0,
    "greetings_refused": 0,
    "visits": 1,
    "page_views": 1
  },
  (...)
]
		

Add custom visitor details

Displays additional information about the visitor in LiveChat apps.

For example, if you have your own database with additional details about your users, you can look up this database based on your visitor’s e-mail address, and display the information from your database for the agent during the chat.

Note: this method can only be used along with the Webhooks. You should create a webhook with chat_started event that will be sent to your integration script. This script must read webhook's license_id and token params and include them in this API method call. See an example integration in Webhooks documentation.

Required properties:

  • license_id – sent by the webhook (read the note above).
  • token – sent by the webhook (read the note above).
  • id – descriptive ID your data set, for example: "my-app". It lets us group the data into one set and display many different data sets for single visitor. It should include only alphanumeric characters (letters, digits, punctuation marks).
  • fields – array of data objects that include name and value properties. This is the actual data that you have about your visitor. This data will be displayed to the agent during the chat.
    For the links you can also pass the anchor text. By adding url param, the value field would act as the anchor.

Optional properties:

  • icon – address of the icon picture that will be displayed in the LiveChat app next to visitor’s data. It lets you group important information.
    icon should be a URL without the http:// prefix. Your web server should support serving the icon file using https:// (SSL) protocol. The icon’s dimensions must be 64x64 px.

Path

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

Example request

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

Example JSON request

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

Example response

{
  "result": "Visitor details added"
}

Webhooks

Webhooks give a variety of ways to integrate LiveChat with external services.

Visit our thorough tutorial on how to start using webhooks. It includes a number of use-cases that webhooks can be used in.

Available paths

[GET]    /webhooks
[POST]   /webhooks
[DELETE] /webhooks/<ID>

Display configured webhooks

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

Path

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

Example request

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

Example response

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

Creates a new webhook.

Required properties:

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

Additional info:

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

  • chat_started – when the chat is started,
  • chat_ended – when the chat is ended,
  • visior_queued – when the visitor enters the queue before a chat,
  • ticket_created – when a new ticket is created.

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

  • chat (only supported in chat_started and chat_ended event types),
  • visitor (only supported in chat_started, chat_ended and visitor_queued event types),
  • pre_chat_survey (only supported in chat_started and chat_ended event types),
  • ticket (only supported in ticket_created event type).

Path

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

Example request

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

Example response

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

Deletes a webhook.

Path

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

Example request

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

Example response

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