Reports API

Introduction

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

Versioning

This document describes the LiveChat Reports API v3.5. This is the latest stable version recommended for the production use. Read more about versioning...

Authorization

You can authorize your calls to the Reports API using one of the following methods:

Postman collection

You can find all the requests from the Reports API v3.5 in Postman. In our collection, we use environment variables that store, for example, the access token. Importing the collection from the link below downloads the environment as well. Remember to replace sample tokens with your own.

Methods

The API endpoint
`https://api.livechatinc.com/v3.5/reports/<resource>/<action>`

Headers

Common headers for all methods:

Header	Value	Required	Notes
`Authorization`	`Bearer <token>`	Yes	Your access token
`X-API-Version`	`3.5`	No	The API version. You can also specify it in the URL.

Additional headers specifically for the POST methods:

Header	Value	Required
`Content-Type`	`application/json`	Yes

Available methods


Chats	`duration` `tags` `total_chats` `ratings` `ranking` `engagement` `greetings_conversion` `forms` `response_time` `first_response_time`
Agents	`availability` `performance`
Tags	`chat_usage`

Available parameters and filters

For the Chats reports

Parameter	Required	Data type	Notes
`distribution`	No	`string`	Allowed values: `hour`, `day`, `day-hours`, `month` or `year`. Defaults to `day`.
`timezone`	No	`string`	IANA Time Zone (e.g. America/Phoenix). By default, the timezone is taken from the request. If it isn't provided, then it's taken from the agent's timezone. When it's impossible to load the agent's timezone, `filters.from` is parsed to get it.
`filters`	No	`object`	If none provided, your report will span the last seven days.
`filters.from`	No	`string`	Filters out chats that took place within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.to`	No	`string`	Filters out chats that took place within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.properties.<namespace>.<name>.<filter_type>`¹	No	`any`	Described below.
`filters.agents.<string_filter_type>`²	No	`any`	Described below; `exists` set to `false` will return unassigned chats; `true` will return the assigned ones.
`filters.tags.<string_filter_type>`²	No	`any`	Described below.
`filters.sales.<integer_filter_type>`³	No	`any`	Described below.
`filters.goals.<integer_filter_type>`³	No	`any`	Described below.
`filters.surveys.<survey>`⁴	No	`array`	Described below.
`filters.event_types.<event_type_filter_type>`⁵	No	`any`	Described below.
`filters.groups.<integer_filter_type>`³	No	`array`	Array of group IDs.
`filters.greetings.from`	No	`string`	Filters out chats started from a greeting that was sent within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.greetings.to`	No	`string`	Filters out chats started from a greeting that was sent within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.greetings.<filter_type>`¹	No	`any`	Described below.
`filters.greetings.groups.<integer_filter_type>`³	No	`any`	Described below.
`filters.agent_response.exists`	No	`bool`
`filters.agent_response.first`	No	`bool`	Modifier that makes the other `agent_response` filters operate exclusively on the agents' first response.
`filters.agent_response.agents.<string_filter_type>`²	No	`any`	Described below. Works only if the `agent_response.first` filter is set to `true`.
`filters.agent_response.groups.<integer_filter_type>`³	No	`any`	Described below. Works only if the `agent_response.first` filter is set to `true`.
`filters.customer_countries.<string_filter_type>`²	No	`any`	Described below. It supports country codes with the `ISO 3166-1 Alpha-2` format.

If filters are provided, they must contain exactly one pair of time-based filters (filters.from/to, filters.greetings.from/to, or filters.surveys.from/to).

For the Agents reports

Parameter	Required	Data type	Notes
`distribution`	No	`string`	Allowed values: `hour`, `day`. Defaults to `day`.
`timezone`	No	`string`	IANA Time Zone (e.g. America/Phoenix). By default, the timezone is taken from the request. If it isn't provided, then it's taken from the agent's timezone. When it's impossible to load the agent's timezone, `filters.from` is parsed to get it.
`filters`	No	`object`	If none provided, your report will span the last seven days.
`filters.from`	No	`string`	Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.to`	No	`string`	Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.agents.<string_filter_type>`²	No	`any`	Described below.
`filters.groups.values`	No	`array`	Array of group IDs.

If filters are provided, they must contain exactly one time-based filter (filters.from/to).

1) <filter_type> can take the following values:

exists (bool)
values (type[] - an array with a specific type for property: string, int or bool)
exclude_values (type[] - an array with a specific type for property: string, int or bool)

There's only one value allowed for a single property.

List of default properties can be found here.

2) <string_filter_type> can take the following values:

exists (bool) - 💡 available only for the Chats parameter value
values (string[] - an array of strings)
exclude_values (string[] - an array of strings)
require_every_value (bool) - if set to true, will return only those chats that have all elements passed in values or exclude_values

You can pass only one of the following values at a time: exists, values or exclude_values.

3) <integer_filter_type> can take the following values:

exists (bool)
values (int[] - an array of integers)
exclude_values (int[] - an array of integers)
require_every_value (bool) - if set to true, will return only those chats that have all elements passed in values or exclude_values

You can pass only one of the following values at a time: exists, values or exclude_values.

4) <survey> contains the following fields:

type (string) - allowed values: pre_chat, post_chat
values (string[]) - an array of answer_ids
exclude_values (string[]) - an array of answer_ids
from (string) - date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
to (string) - date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
exists (bool) - if set to true, will return only surveys with survey_id
groups (<integer_filter_type>³)

Sample survey filter

Copied!

{
	"surveys": [
		{
			"type": "pre_chat",
			"from": "2021-01-01T00:00:00-00:00",
			"to": "2021-04-15T23:59:59-00:00",
			"values": [
				"163672098710307655:0"
			],
			"groups": {
				"values": [
					10
				]
			}
		},
		{
			"type": "post_chat",
			"from": "2021-01-01T00:00:00-00:00",
			"to": "2021-04-15T23:59:59-00:00",
			"exclude_values": [
				"183672098710307678:1"
			]
		}
	]
}

5) <event_type_filter_type> can take the following values:

values (string[] - an array of Event types, duplicates are ignored)
exclude_values (string[] - an array of Event types, duplicates are ignored)
require_every_value (bool) - if set to true, will return only those chats that have all elements passed in values or exclude_values

You can pass only one of the following values at a time: exists, values or exclude_values.

Sample filters

Copied!

{
	"from": "2021-01-01T00:00:00-00:00",
	"to": "2021-04-15T23:59:59-00:00",
	"properties": {
		"routing": {
			"continuous": {
				"values": [
					true
				]
			}
		}
	},
	"agents": {
		"values": [
			"joe@acme.com",
			"alice@acme.com"
		]
	},
	"tags": {
		"exclude_values": [
			"spam"
		]
	},
	"event_types": {
		"values": [
			"file"
		]
	}
}

The JSON payload above translates into the following query string:

FILTERS AS QUERY STRING PARAMS

Copied!

?filters.from=2021-03-01T23:59:59-00:00
&filters.to=2021-04-13T23:59:59-00:00
&filters.properties[routing][continuous].values=true
&filters.agents.values=joe@acme.com
&filters.agents.values=alice@acme.com
&filters.tags.exclude_values=spam
&filters.event_types.values=file

💡 Notice the square brackets [] when using GET query string params to define properties.<namespace> and properties.<namespace>.<name>.

Chats

Duration

Shows the average chatting duration of agents within a license.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/duration`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains `distribution` objects, for example, `day`.
`records.day.count`	The total number of chats `agents` had that `day`.
`records.day.agents_chatting_duration`	The average chat duration `agents` had that `day`.
`records.day.duration`	The average chat duration for that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/duration \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "distribution": "day",
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "duration-report",
	"total": 369,
	"records": {
		"2021-04-08": {
			"agents_chatting_duration": 10800,
			"count": 37,
			"duration": 12100
		},
		"2021-04-09": {
			"agents_chatting_duration": 7200,
			"count": 48,
			"duration": 8400
		},
		"2021-04-10": {
			"agents_chatting_duration": 3600,
			"count": 59,
			"duration": 4000
		},
		"2021-04-11": {
			"agents_chatting_duration": 10800,
			"count": 21,
			"duration": 12200
		},
		"2021-04-12": {},
		"2021-04-13": {
			"agents_chatting_duration": 7200,
			"count": 33,
			"duration": 8000
		},
		"2021-04-14": {},
		"2021-04-15": {
			"agents_chatting_duration": 3600,
			"count": 171,
			"duration": 5500
		}
	}
}


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/tags`
HTTP method	POST, GET
Required scopes	`reports_read`

Total Chats

Shows how many chats occurred during the specified period.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/total_chats`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.total`	The total number of chats that `day`.
`records.day.continuous`	The number of continuous chats that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/total_chats \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "distribution": "day",
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "total-chats-report",
	"total": 369,
	"records": {
		"2021-04-08": {
			"total": 37,
			"continuous": 15
		},
		"2021-04-09": {
			"total": 48,
			"continuous": 1
		},
		"2021-04-10": {
			"total": 59,
			"continuous": 51
		},
		"2021-04-11": {
			"total": 21,
			"continuous": 7
		},
		"2021-04-12": {},
		"2021-04-13": {
			"total": 33,
			"continuous": 30
		},
		"2021-04-14": {},
		"2021-04-15": {
			"total": 171,
			"continuous": 52
		}
	}
}

Ratings

Shows the number of rated chats along with their ratings during a specified period of time.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/ratings`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.chats`	The total number of chats that `day`.
`records.day.bad`	The number of chats rated `bad` that `day`.
`records.day.good`	The number of chats rated `good` that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/ratings \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "distribution": "day",
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "ratings-report",
	"total": 83,
	"records": {
		"2021-04-08": {
			"bad": 6,
			"chats": 10,
			"good": 5
		},
		"2021-04-09": {
			"bad": 8,
			"chats": 23,
			"good": 10
		},
		"2021-04-10": {
			"bad": 2,
			"chats": 17,
			"good": 10
		},
		"2021-04-11": {
			"bad": 1,
			"chats": 3
		},
		"2021-04-12": {},
		"2021-04-13": {
			"chats": 2
		},
		"2021-04-14": {},
		"2021-04-15": {
			"chats": 28,
			"good": 7
		}
	}
}

Ranking

Shows the ratio of good to bad ratings for each operator.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/ranking`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters. 💡 Notice that the distribution parameter will have no effect on the response of this method.

Response

Field	Notes
`records`	Contains the `agent` objects.
`records.agent.total`	The total number of chats an agent had in the specified period.
`records.agent.good`	The number of agent's chats rated `good`.
`records.agent.bad`	The number of agent's chats rated `bad`.
`records.agent.score`	The agent's score. Read more about how we calculate agent rankings...

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/ranking \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "ranking-report",
	"records": {
		"smith@example.com": {
			"total": 2,
			"good": 0,
			"bad": 2,
			"score": 0.11473482425785904
		},
		"agent@example.com": {
			"total": 19,
			"good": 13,
			"bad": 6,
			"score": 0.42326713031463276
		}
	}
}

Engagement

Shows the distribution of chats based on engagement during the specified period.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/engagement`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.total`	The total number of chats that `day`.
`records.day.started_by_customer_from_greeting`	The number of chats from greetings (also knows as targeted messages) that `day`.
`records.day.started_by_customer_without_greeting`	The number of chats started by a customer that `day`.
`records.day.started_by_agent`	The number of chats started by an agent that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/engagement \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "distribution": "day",
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "engagement-report",
	"total": 7411,
	"records": {
		"2021-08-16": {
			"started_by_customer_from_greeting": 187,
			"started_by_customer_without_greeting": 689,
			"started_by_agent": 3
		},
		"2021-08-17": {
			"started_by_customer_from_greeting": 362,
			"started_by_customer_without_greeting": 1257,
			"started_by_agent": 2
		},
		"2021-08-18": {
			"started_by_customer_from_greeting": 339,
			"started_by_customer_without_greeting": 1247,
			"started_by_agent": 1
		},
		"2021-08-19": {
			"started_by_customer_from_greeting": 315,
			"started_by_customer_without_greeting": 1147,
			"started_by_agent": 1
		},
		"2021-08-20": {
			"started_by_customer_from_greeting": 277,
			"started_by_customer_without_greeting": 1051
		},
		"2021-08-21": {
			"started_by_customer_from_greeting": 240,
			"started_by_customer_without_greeting": 762
		},
		"2021-08-22": {
			"started_by_customer_from_greeting": 239,
			"started_by_customer_without_greeting": 729,
			"started_by_agent": 1
		},
		"2021-08-23": {
			"started_by_customer_from_greeting": 153,
			"started_by_customer_without_greeting": 529
		}
	}
}

Greetings Conversion

Shows the number of greetings sent to the customers and how many of those resulted in a chat or a goal. Greetings are also known as targeted messages.

The method will return only up to 100 values for each day. If there are more than 100 values, use the LiveChat App to access the full data for a given day.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/greetings_conversion`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.greeting_id.accepted`	The number of chats started as a result of accepting a greeting that `day`.
`records.day.greeting_id.canceled`	The number of greetings customers dismissed that `day`.
`records.day.greeting_id.displayed`	The number of greetings displayed that `day`.
`records.day.greeting_id.goals`	The number of goals resulted from the greetings that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/greetings_conversion \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
   "distribution": "day",
   "filters": {
      "greetings": {
         "from": "2021-04-08T00:00:00-00:00",
         "to": "2021-04-15T23:59:59-00:00",
         "groups": {
            "values": [1]
         }
      }
   }
}'

Response

Copied!

{
	"name": "greetings-conversion-report",
	"total": 3,
	"records": {
		"2021-09-20": {},
		"2021-09-21": {},
		"2021-09-22": {},
		"2021-09-23": {},
		"2021-09-24": {},
		"2021-09-25": {},
		"2021-09-26": {},
		"2021-09-27": {
			"1": {
				"accepted": 1,
				"canceled": 0,
				"displayed": 2,
				"goals": 0
			},
			"18": {
				"accepted": 0,
				"canceled": 0,
				"displayed": 1,
				"goals": 0
			},
			"19": {
				"accepted": 2,
				"canceled": 0,
				"displayed": 2,
				"goals": 0
			}
		},
		"2021-09-28": {}
	}
}

Forms

Returns the number of submitted chat forms along with the count of specific answers.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/forms`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters. 💡 Notice that the distribution parameter will have no effect on the response of this method.

Response

Field	Notes
`records`	Contains `form` objects.
`records[{form_index}]`	Form at a given index.
`records[{form_index}].form_id`	Form ID.
`records[{form_index}].count`	Number of times this form was filled.
`records[{form_index}].group_id`	Group ID in which this `form` is.
`records[{form_index}].fields`	Contains `field` objects.
`records[{form_index}].fields[{field_index}]`	Field at a given index.
`records[{form_index}].fields[{field_index}].field_id`	Field ID.
`records[{form_index}].fields[{field_index}].label`	Text label of form field.
`records[{form_index}].fields[{field_index}].answers`	List of `answer` objects.
`records[{form_index}].fields[{field_index}].answers[{answer_index}]`	Answer at a given index.
`records[{form_index}].fields[{field_index}].answers[{answer_index}].answer_id`	Answer ID.
`records[{form_index}].fields[{field_index}].answers[{answer_index}].label`	Text label of answer.
`records[{form_index}].fields[{field_index}].answers[{answer_index}].count`	Number of times this answer was selected for this field.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/forms \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "form-report",
	"records": [
		{
			"form_id": "163654772984908812",
			"count": 5,
			"group_id": 0,
			"fields": [
				{
					"field_id": "163654772984903574",
					"label": "Question:",
					"answers": [
						{
							"answer_id": 0,
							"label": "First answer",
							"count": 3
						},
						{
							"answer_id": 1,
							"label": "Second answer",
							"count": 2
						}
					]
				}
			]
		}
	]
}

Response Time

Shows the average agents' response time within a licence.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/response_time`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.count`	The total number of chats that `day`.
`records.day.response_time`	The average chat response time for that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/response_time \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "response-time-report",
	"total": 39,
	"records": {
		"2021-04-08": {
			"count": 3,
			"response_time": 14.22
		},
		"2021-04-09": {
			"count": 4,
			"response_time": 41.35
		},
		"2021-04-10": {
			"count": 3,
			"response_time": 10.1
		},
		"2021-04-11": {
			"count": 9,
			"response_time": 3.34
		},
		"2021-04-12": {},
		"2021-04-13": {
			"count": 5,
			"response_time": 8.5
		},
		"2021-04-14": {},
		"2021-04-15": {
			"count": 6,
			"response_time": 32.3
		}
	}
}

First Response Time

Shows the average agents' first response time within a licence.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/chats/first_response_time`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`total`	The total number of chats in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.day.count`	The total number of chats that `day`.
`records.day.first_response_time`	The average chat first response time for that `day`.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/first_response_time \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "first-response-time-report",
	"total": 39,
	"records": {
		"2021-04-08": {
			"count": 3,
			"first_response_time": 14.22
		},
		"2021-04-09": {
			"count": 4,
			"first_response_time": 41.35
		},
		"2021-04-10": {
			"count": 3,
			"first_response_time": 10.1
		},
		"2021-04-11": {
			"count": 9,
			"first_response_time": 3.34
		},
		"2021-04-12": {},
		"2021-04-13": {
			"count": 5,
			"first_response_time": 8.5
		},
		"2021-04-14": {},
		"2021-04-15": {
			"count": 6,
			"first_response_time": 32.3
		}
	}
}

Agents

Availability

Shows for how long an agent, group, or the whole account was available for chatting during a specified period of time.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/agents/availability`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters. Depending on the distribution parameter the response will contain a different time resolution.

Response

Field	Notes
`total`	Total time the chat was available in the specified date range.
`records`	Contains the `distribution` objects, for example, `day`.
`records.hours`	The total number of hours the chat was available that `day` (only for the `day` distribution).
`records.minutes`	The total number of minutes the chat was available that `hour` (only for the `hour` distribution).

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/agents/availability \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "availability-report",
	"total": 19.59,
	"records": {
		"2021-04-08": {
			"hours": 0
		},
		"2021-04-09": {
			"hours": 0
		},
		"2021-04-10": {
			"hours": 0.15
		},
		"2021-04-11": {
			"hours": 7.85
		},
		"2021-04-12": {
			"hours": 7.99
		},
		"2021-04-13": {
			"hours": 2.28
		},
		"2021-04-14": {
			"hours": 1.32
		},
		"2021-04-15": {
			"hours": 0
		}
	}
}

Performance

Shows the total number of agent's chats, the number of good and bad rates they received, and how well they performed in the early stages of a chat. Additionally, the report shows the time an agent spent chatting, accepting and not accepting chats, as well as the total time they were logged in.

Specifics


Method URL	`https://api.livechatinc.com/v3.5/reports/agents/performance`
HTTP method	POST, GET
Required scopes	`reports_read`

Request

See available parameters and filters.

Response

Field	Notes
`summary`	Summary for all agents.
`summary.chats_count`	The total number of chats the agents had in the specified period of time.
`summary.chats_rated_good`	The number of chats rated `good`.
`summary.chats_rated_bad`	The number of chats rated `bad`.
`summary.first_response_chats_count`	The total number of chats in which the agents have replied to the first message sent by the customers.
`summary.first_response_time`	The average time in seconds the agents took to send a first reply to the customers' messages.
`records`	Contains the `agent` objects.
`records.chats_count`	The total number of chats the agent had in the specified period of time.
`records.chats_rated_good`	The number of agent's chats rated `good`.
`records.chats_rated_bad`	The number of agent's chats rated `bad`.
`records.first_response_chats_count`	The number of chats where the agent has replied to the first message sent by the customer.
`records.first_response_time`	The average time in seconds the agent took to send a first reply to the customers' messages.
`records.accepting_chats_time`	The time in seconds during which the agent had the `accepting_chats` status set.
`records.chatting_time`	The time in seconds during which the agent was chatting.
`records.logged_in_time`	The time in seconds during which the agent was logged in.
`records.not_accepting_chats_time`	The time in seconds during which the agent had the `not_accepting_chats` status set.

REQUEST

Copied!

curl -X POST \
https://api.livechatinc.com/v3.5/reports/agents/performance \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
    "filters": {
      "from": "2021-04-08T00:00:00-00:00",
      "to": "2021-04-15T23:59:59-00:00"
    }
  }'

Response

Copied!

{
	"name": "performance-report",
	"records": {
		"smith@example.com": {
			"accepting_chats_time": 35296,
			"chats_count": 4,
			"chats_rated_bad": 0,
			"chats_rated_good": 2,
			"chatting_time": 55,
			"first_response_chats_count": 3,
			"first_response_time": 9.666666666666666,
			"logged_in_time": 45304,
			"not_accepting_chats_time": 10008
		},
		"agent@example.com": {
			"accepting_chats_time": 24567,
			"chats_count": 13,
			"chats_rated_bad": 3,
			"chats_rated_good": 5,
			"chatting_time": 275,
			"first_response_chats_count": 8,
			"first_response_time": 8.133333,
			"logged_in_time": 32110,
			"not_accepting_chats_time": 7543
		}
	},
	"summary": {
		"chats_count": 17,
		"chats_rated_bad": 3,
		"chats_rated_good": 7,
		"first_response_chats_count": 11,
		"first_response_time": 8.55151490909091
	}
}


Method URL	`https://api.livechatinc.com/v3.5/reports/tags/chat_usage`
HTTP method	POST, GET
Required scopes	`reports_read`

Parameter	Required	Data type	Notes
`timezone`	No	`string`	IANA Time Zone (e.g. America/Phoenix). By default, the timezone is taken from the request. If it isn't provided, then it's taken from the agent's timezone. When it's impossible to load the agent's timezone, `filters.from` is parsed to get it.
`filters`	No	`object`	If none provided, your report will span the last seven days.
`filters.from`	No	`string`	Filters out chats that took place within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.to`	No	`string`	Filters out chats that took place within the time range defined as <`from`,`to`>. Date & time format compatible with RFC3339 with optional resolution of microseconds, `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
`filters.groups.values`	No	`[]int`	Array of group IDs.

Field	Notes
`records`	Contains the `<tag>:<chat_count>` pairs.

Contact us

If you found a bug or a typo, you can create an issue on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@livechat.com

Reports API.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

Versioning

Authorization

Postman collection

Methods

Headers

Available methods

Available parameters and filters

For the Chats reports

For the Agents reports

Chats

Duration

Specifics

Request

Response

Tags

Specifics

Request

Response

Total Chats

Specifics

Request

Response

Ratings

Specifics

Request

Response

Ranking

Specifics

Request

Response

Engagement

Specifics

Request

Response

Greetings Conversion

Specifics

Request

Response

Forms

Specifics

Request

Response

Response Time

Specifics

Request

Response

First Response Time

Specifics

Request

Response

Agents

Availability

Specifics

Request

Response

Performance

Specifics

Request

Response

Tags

Chat Usage

Specifics

Request

Response

Contact us

Reports API