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.2, which is a legacy version. For production-ready applications, it's best to use to the current stable version. Read more about versioning...
Lifecycle headers
API responses will contain one of two headers related to the API lifecycle: Legacy or Deprecation. These headers specify when the associated stage ends (in the YYYY-MM-DD format).
Authorization
You can authorize your calls to the Reports API using one of the following methods:
Postman Collection
Use the Postman Collection to try out the requests from the Reports API v3.2.
Methods
| The API endpoint |
|---|
https://api.livechatinc.com/v3.2/reports/<resource>/<action> |
| Header | Value | Required | Notes |
|---|---|---|---|
Authorization | Bearer <token> | Yes | Your access token |
X-API-Version | 3.2 | No | You can specify the API version in the URL instead. |
| Response Header | Value | Notes |
|---|---|---|
Legacy | YYYY-MM-DD | The date when the legacy stage ends. |
Deprecation | YYYY-MM-DD | The date when the deprecated stage ends. |
Available methods
Chats
Agents Chatting Duration
Shows the average chatting duration of agents within a license.
Specifics
| Method URL | https://api.livechatinc.com/v3.2/reports/chats/agents_chatting_duration |
| HTTP method | GET |
| Required scopes | reports_read |
Request
| Query String | Required | Notes |
|---|---|---|
to | yes | Date in the RFC3339 format |
from | yes | Date in the RFC3339 format |
agents | no | Agent emails separated by a comma; if not specified, returns the data for all agents within the license |
groups | no | Group IDs separated by a comma |
tags | no | Names of tags separated by a comma |
customer_client_ids | no | Client IDs separated by a comma |
distribution | no | Possible values: hour, day-hours, day, month; defaults to day |
tagged | no | Possible values: true, 1, false, 0 |
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.seconds | The average chat duration agents had that day. |
REQUESTcurl "https://api.livechatinc.com/v3.2/reports/chats/agents_chatting_duration?from=2020-09-01T00:00:00%2B02:00&to=2020-09-14T23:59:59%2B02:00" \
-H 'Authorization: Bearer <your_access_token>'
{
"name": "agents-chatting-duration-report",
"total": 79,
"records": {
"2020-09-01": {},
"2020-09-02": {},
"2020-09-03": {},
"2020-09-04": {},
"2020-09-05": {
"count": 67,
"seconds": 875
},
"2020-09-06": {},
"2020-09-07": {},
"2020-09-08": {},
"2020-09-09": {},
"2020-09-10": {},
"2020-09-11": {
"count": 11,
"seconds": 1337
},
"2020-09-12": {},
"2020-09-13": {},
"2020-09-14": {
"count": 1,
"seconds": 178
}
}
}Tags
Shows the distribution of tags for chats.
Specifics
| Method URL | https://api.livechatinc.com/v3.2/reports/chats/tags |
| HTTP method | GET |
| Required scopes | reports_read |
Request
| Query String | Required | Notes |
|---|---|---|
to | yes | Date in the RFC3339 format |
from | yes | Date in the RFC3339 format |
distribution | yes | Possible values: hour, day-hours, day, month, year |
agents | no | Agent emails separated by a comma; if not specified, returns the data for all agents within the license. |
groups | no | Group IDs separated by a comma |
names | no | The names of tags separated by a comma; when tags=:without:, you will get the total number of chats without tags, when tags=:with: you will get the total number of chats with tags. |
Response
| Field | Notes |
|---|---|
total | The total number of chats in the specified date range. |
records | Contains the distribution objects, for example, day. |
records.day.<tag> | The total number of chats tagged with <tag>. |
REQUESTcurl "https://api.livechatinc.com/v3.2/reports/chats/tags?from=2020-09-01T00:00:00%2B02:00&to=2020-09-14T23:59:59%2B02:00&distribution=day" \
-H 'Authorization: Bearer <your_access_token>'
{
"name": "tags-report",
"total": 329,
"records": {
"2020-09-01": {},
"2020-09-02": {},
"2020-09-03": {},
"2020-09-04": {},
"2020-09-05": {
"spam": 21,
"support": 12
},
"2020-09-06": {},
"2020-09-07": {},
"2020-09-08": {},
"2020-09-09": {},
"2020-09-10": {},
"2020-09-11": {
"spam": 13,
"support": 7
},
"2020-09-12": {},
"2020-09-13": {},
"2020-09-14": {
"spam": 98,
"support": 178
}
}
}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