API version

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.4. This is the developer preview version that provides a preview of the upcoming changes to the API. It's not open to public use. However, if you want to test some features, contact us at developers@livechat.com or ask on the chat, and we'll give you access.

Authorization

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

Methods

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

Headers

Common headers for all methods:

HeaderValueRequiredNotes
AuthorizationBearer <token>YesYour access token
X-API-Version3.4NoThe API version. You can also specify it in the URL.

Additional headers specifically for the POST methods:

HeaderValueRequired
Content-Typeapplication/jsonYes

Available methods

Chatsduration tags total_chats ratings ranking engagement
Agentsavailability

Available parameters and filters

For the Chats reports

ParameterRequiredData typeNotes
distributionNostringAllowed values: hour, day, day-hours, month or year. Defaults to day.
timezoneNostringIANA Time Zone (e.g. America/Phoenix). Defaults to the requester's timezone. When the requester's timezone isn't present, then filters.from is parsed to get the timezone.
filtersNoobjectIf none provided, your report will span the last seven days.
filters.fromNostringDate & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM.
filters.toNostringDate & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM.
filters.properties.<namespace>.<name>.<filter_type>1NoanyDescribed below.
filters.agents.<string_filter_type>2NoanyDescribed below; exists set to false will return unassigned chats; true will return the assigned ones.
filters.tags.<string_filter_type>2NoanyDescribed below.
filters.sales.<integer_filter_type>3NoanyDescribed below.
filters.goals.<integer_filter_type>3NoanyDescribed below.
filters.surveys.<survey>4NoarrayDescribed below.
filters.event_types.<event_type_filter_type>5NoanyDescribed below.
filters.groups.valuesNoarrayArray of group IDs.

For the Agents reports

ParameterRequiredData typeNotes
distributionNostringAllowed values: hour, day. Defaults to day.
timezoneNostringIANA Time Zone (e.g. America/Phoenix). Defaults to the requester's timezone. When the requester's timezone isn't present, then filters.from is parsed to get the timezone.
filtersNoobjectIf none provided, your report will span the last seven days.
filters.fromNostringDate & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM.
filters.toNostringDate & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssssZHH:MM.
filters.agents.<string_filter_type>2NoanyDescribed below.
filters.groups.valuesNoarrayArray of group IDs.

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
  • answer_id (string)

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 URLhttps://api.livechatinc.com/v3.4/reports/chats/duration
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

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.agents_chatting_durationThe average chat duration agents had that day.
records.day.durationThe average chat duration for that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.4/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
		}
	}
}

Tags

Shows the distribution of tags for chats.

Specifics
Method URLhttps://api.livechatinc.com/v3.4/reports/chats/tags
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

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 -X POST \
https://api.livechatinc.com/v3.4/reports/chats/tags \
  -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": "tags-report",
	"total": 369,
	"records": {
		"2021-04-08": {
			"spam": 14,
			"support": 19
		},
		"2021-04-09": {
			"spam": 22,
			"support": 34
		},
		"2021-04-10": {
			"spam": 42,
			"support": 18
		},
		"2021-04-11": {
			"spam": 12,
			"support": 5
		},
		"2021-04-12": {},
		"2021-04-13": {
			"spam": 7,
			"support": 5
		},
		"2021-04-14": {},
		"2021-04-15": {
			"spam": 11,
			"support": 27
		}
	}
}

Total Chats

Shows how many chats occurred during the specified period.

Specifics
Method URLhttps://api.livechatinc.com/v3.4/reports/chats/total_chats
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

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 -X POST \
https://api.livechatinc.com/v3.4/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 URLhttps://api.livechatinc.com/v3.4/reports/chats/ratings
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

Response
FieldNotes
totalThe total number of chats in the specified date range.
recordsContains the distribution objects, for example, day.
records.day.chatsThe total number of chats that day.
records.day.badThe number of chats rated bad that day.
records.day.goodThe number of chats rated good that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.4/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 URLhttps://api.livechatinc.com/v3.4/reports/chats/ranking
HTTP methodPOST, GET
Required scopesreports_read
Request

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

Response
FieldNotes
recordsContains the agent objects.
records.agent.totalThe total number of chats an agent had in the specified period.
records.agent.goodThe number of agent's chats rated good.
records.agent.badThe number of agent's chats rated bad.
records.agent.scoreThe agent's score. Read more about how we calculate agent rankings...
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.4/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 URLhttps://api.livechatinc.com/v3.4/reports/chats/engagement
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

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.auto_inviteThe number of chats from greetings (also knows as targeted messages) that day.
records.day.immediate_startThe number of chats started by a customer that day.
records.day.manual_inviteThe number of chats started by an agent that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.4/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": {
			"auto_invite": 187,
			"immediate_start": 689,
			"manual_invite": 3
		},
		"2021-08-17": {
			"auto_invite": 362,
			"immediate_start": 1257,
			"manual_invite": 2
		},
		"2021-08-18": {
			"auto_invite": 339,
			"immediate_start": 1247,
			"manual_invite": 1
		},
		"2021-08-19": {
			"auto_invite": 315,
			"immediate_start": 1147,
			"manual_invite": 1
		},
		"2021-08-20": {
			"auto_invite": 277,
			"immediate_start": 1051
		},
		"2021-08-21": {
			"auto_invite": 240,
			"immediate_start": 762
		},
		"2021-08-22": {
			"auto_invite": 239,
			"immediate_start": 729,
			"manual_invite": 1
		},
		"2021-08-23": {
			"auto_invite": 153,
			"immediate_start": 529
		}
	}
}

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 URLhttps://api.livechatinc.com/v3.4/reports/agents/availability
HTTP methodPOST, GET
Required scopesreports_read
Request

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

Response
FieldNotes
totalTotal time the chat was available in the specified date range.
recordsContains the distribution objects, for example, day.
records.hoursThe total number of hours the chat was available that day (only for the day distribution).
records.minutesThe 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.4/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
		}
	}
}

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