API version

Reports API

1 minutes reading time

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.

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.

Run in Postman

Methods

The API endpoint
https://api.livechatinc.com/v3.3/reports/<resource>/<action>
HeaderValueRequiredNotes
AuthorizationBearer <token>YesYour access token
X-API-Version3.3NoYou can specify the API version in the URL instead.

Available methods

Chatsagents_chatting_duration tags total_chats

Chats

Agents Chatting Duration

Shows the average chatting duration of agents within a license.

Specifics
Method URLhttps://api.livechatinc.com/v3.3/reports/chats/agents_chatting_duration
HTTP methodGET
Required scopes-
Request
Query StringRequiredNotes
toyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
fromyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
agentsnoAgent emails separated by a comma; if not specified, returns the data for all agents within the license.
groupsnoGroup IDs separated by a comma
tagsnoNames of tags separated by a comma
customer_client_idsnoClient IDs separated by a comma
distributionnoPossible values: hour, day-hours, day, month; defaults to day
timezonenoTimezone 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.
taggednoPossible values: true, 1, false, 0
Response
FieldNotes
totalThe total number of chats in the specified date range.
recordsContains distribution objects, for example, day.
records.day.countThe total number of chats agents had that day.
records.day.secondsThe 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 URLhttps://api.livechatinc.com/v3.3/reports/chats/tags
HTTP methodGET
Required scopes-
Request
Query StringRequiredNotes
toyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
fromyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
distributionyesPossible values: hour, day-hours, day, month, year
timezonenoTimezone 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.
agentsnoAgent emails separated by a comma; if not specified, returns the data for all agents within the license.
groupsnoGroup IDs separated by a comma
namesnoThe 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
FieldNotes
totalThe total number of chats in the specified date range.
recordsContains 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 URLhttps://api.livechatinc.com/v3.3/reports/chats/total_chats
HTTP methodGET
Required scopes-
Request
Query StringRequiredNotes
toyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
fromyesDate in the RFC3339 format, which also contains a timezone. This timezone will be used if no timezone is provided.
distributionnoPossible values: hour, day-hours, day, month; defaults to day
timezonenoTimezone 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.
agentsnoAgent emails separated by a comma; if not specified, returns the data for all agents within the license.
agent_assignednoPossible values: true, 1, false, 0
groupsnoGroup IDs separated by a comma
customer_client_idsnoClient IDs separated by a comma
tagsnoNames of tags separated by a comma
taggednoPossible values: true, 1, false, 0
Response
FieldNotes
totalThe total number of chats in the specified date range.
recordsContains the distribution objects, for example, day.
records.day.totalThe total number of chats that day.
records.day.continuousThe 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