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. This is the latest stable version recommended for the production use.

Authorization

To call the Reports API, you need to use a Bearer access token. Learn how to get it.

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). Defaults to the requester's timezone. If not present, `from` is parsed to get the requester's timezone.
`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). Defaults to the requester's timezone. If not present, `from` is parsed to get the requester's timezone.
`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). Defaults to the requester's timezone. If not present, `from` is parsed to get the requester's timezone.
`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@livechat.com

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

.css-1plb8kr{color:inherit;-webkit-text-decoration:none;text-decoration:none;position:relative;}.css-1plb8kr:hover{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1plb8kr:hover:before{content:"#";position:absolute;font-weight:300;left:-1em;top:1px;opacity:0.3;}Introduction

Reports API

Introduction