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.3, 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

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

Methods

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

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

Available methods


Chats	`agents_chatting_duration` `tags` `total_chats`

Chats

Agents Chatting Duration

Shows the average chatting duration of agents within a license.

Specifics


Method URL	`https://api.livechatinc.com/v3.3/reports/chats/agents_chatting_duration`
HTTP method	GET
Required scopes	`reports_read`

Request

Query String	Required	Notes
`to`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`from`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`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`
`timezone`	no	Timezone in the TZ format (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, `from` is parsed to get it.
`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`.

REQUEST

Copied!

curl "https://api.livechatinc.com/v3.3/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>'

Response

Copied!

{
	"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.3/reports/chats/tags`
HTTP method	GET
Required scopes	`reports_read`

Request

Query String	Required	Notes
`to`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`from`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`distribution`	yes	Possible values: `hour`, `day-hours`, `day`, `month`, `year`
`timezone`	no	Timezone in the TZ format (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,`from` is parsed to get it.
`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>`.

REQUEST

Copied!

curl "https://api.livechatinc.com/v3.3/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>'

Response

Copied!

{
	"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
		}
	}
}

Total Chats

Shows how many chats occurred during the specified period.

Specifics


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

Request

Query String	Required	Notes
`to`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`from`	yes	Date in the RFC3339 format, which also contains a timezone. This timezone will be used if no `timezone` is provided.
`distribution`	no	Possible values: `hour`, `day-hours`, `day`, `month`; defaults to `day`
`timezone`	no	Timezone in the TZ format (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, `from` is parsed to get it.
`agents`	no	Agent emails separated by a comma; if not specified, returns the data for all agents within the license.
`agent_assigned`	no	Possible values: `true`, `1`, `false`, `0`
`groups`	no	Group IDs separated by a comma
`customer_client_ids`	no	Client IDs separated by a comma
`tags`	no	Names of tags separated by a comma
`tagged`	no	Possible values: `true`, `1`, `false`, `0`

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 "https://api.livechatinc.com/v3.3/reports/chats/total_chats?from=2020-09-01T00:00:00%2B02:00&to=2020-09-14T23:59:59%2B02:00" \
  -H 'Authorization: Bearer <your_access_token>'

Response

Copied!

{
	"name": "total-chats-report",
	"total": 329,
	"records": {
		"2020-09-01": {},
		"2020-09-02": {},
		"2020-09-03": {},
		"2020-09-04": {},
		"2020-09-05": {
			"total": 10,
			"continuous": 5
		},
		"2020-09-06": {},
		"2020-09-07": {},
		"2020-09-08": {
			"total": 24
		},
		"2020-09-09": {},
		"2020-09-10": {},
		"2020-09-11": {
			"total": 56,
			"continuous": 33
		},
		"2020-09-12": {},
		"2020-09-13": {},
		"2020-09-14": {
			"total": 111,
			"continuous": 90
		}
	}
}

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@text.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

Lifecycle headers

Authorization

Postman collection

Methods

Available methods

Chats

Agents Chatting Duration

Specifics

Request

Response

Tags

Specifics

Request

Response

Total Chats

Specifics

Request

Response

Contact us

Reports API