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.5. This is the latest stable version recommended for the production use. Read more about versioning...

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.5/reports/<resource>/<action>

Headers

Common headers for all methods:

HeaderValueRequiredNotes
AuthorizationBearer <token>YesYour access token
X-API-Version3.5NoThe 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 greetings_conversion forms response_time first_response_time
Agentsavailability performance
Tagschat_usage

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). 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, filters.from is parsed to get it.
filtersNoobjectIf none provided, your report will span the last seven days.
filters.fromNostringFilters out chats that took place within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.toNostringFilters out chats that took place within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH: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.<integer_filter_type>3NoarrayArray of group IDs.
filters.greetings.fromNostringFilters out chats started from a greeting that was sent within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.greetings.toNostringFilters out chats started from a greeting that was sent within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.greetings.<filter_type>1NoanyDescribed below.
filters.greetings.groups.<integer_filter_type>3NoanyDescribed below.
filters.agent_response.existsNobool
filters.agent_response.firstNoboolModifier that makes the other agent_response filters operate exclusively on the agents' first response.
filters.agent_response.agents.<string_filter_type>2NoanyDescribed below. Works only if the agent_response.first filter is set to true.
filters.agent_response.groups.<integer_filter_type>3NoanyDescribed below. Works only if the agent_response.first filter is set to true.
filters.customer_countries.<string_filter_type>2NoanyDescribed below. It supports country codes with the ISO 3166-1 Alpha-2 format.

If filters are provided, they must contain exactly one pair of time-based filters (filters.from/to, filters.greetings.from/to, or filters.surveys.from/to).

For the Agents reports

ParameterRequiredData typeNotes
distributionNostringAllowed values: hour, day. Defaults to day.
timezoneNostringIANA Time Zone (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, filters.from is parsed to get it.
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.ssssss+HH:MM.
filters.toNostringDate & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.agents.<string_filter_type>2NoanyDescribed below.
filters.groups.valuesNoarrayArray of group IDs.

If filters are provided, they must contain exactly one time-based filter (filters.from/to).

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
  • values (string[]) - an array of answer_ids
  • exclude_values (string[]) - an array of answer_ids
  • from (string) - date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
  • to (string) - date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM
  • exists (bool) - if set to true, will return only surveys with survey_id
  • groups (<integer_filter_type>3)
Sample survey filter
Copied!
{
	"surveys": [
		{
			"type": "pre_chat",
			"from": "2021-01-01T00:00:00-00:00",
			"to": "2021-04-15T23:59:59-00:00",
			"values": [
				"163672098710307655:0"
			],
			"groups": {
				"values": [
					10
				]
			}
		},
		{
			"type": "post_chat",
			"from": "2021-01-01T00:00:00-00:00",
			"to": "2021-04-15T23:59:59-00:00",
			"exclude_values": [
				"183672098710307678:1"
			]
		}
	]
}

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

Greetings Conversion

Shows the number of greetings sent to the customers and how many of those resulted in a chat or a goal. Greetings are also known as targeted messages.

The method will return only up to 100 values for each day. If there are more than 100 values, use the LiveChat App to access the full data for a given day.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/chats/greetings_conversion
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.greeting_id.acceptedThe number of chats started as a result of accepting a greeting that day.
records.day.greeting_id.canceledThe number of greetings customers dismissed that day.
records.day.greeting_id.displayedThe number of greetings displayed that day.
records.day.greeting_id.goalsThe number of goals resulted from the greetings that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/greetings_conversion \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -d '{
   "distribution": "day",
   "filters": {
      "greetings": {
         "from": "2021-04-08T00:00:00-00:00",
         "to": "2021-04-15T23:59:59-00:00",
         "groups": {
            "values": [1]
         }
      }
   }
}'
Response
Copied!
{
	"name": "greetings-conversion-report",
	"total": 3,
	"records": {
		"2021-09-20": {},
		"2021-09-21": {},
		"2021-09-22": {},
		"2021-09-23": {},
		"2021-09-24": {},
		"2021-09-25": {},
		"2021-09-26": {},
		"2021-09-27": {
			"1": {
				"accepted": 1,
				"canceled": 0,
				"displayed": 2,
				"goals": 0
			},
			"18": {
				"accepted": 0,
				"canceled": 0,
				"displayed": 1,
				"goals": 0
			},
			"19": {
				"accepted": 2,
				"canceled": 0,
				"displayed": 2,
				"goals": 0
			}
		},
		"2021-09-28": {}
	}
}

Forms

Returns the number of submitted chat forms along with the count of specific answers.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/chats/forms
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 form objects.
records[{form_index}]Form at a given index.
records[{form_index}].form_idForm ID.
records[{form_index}].countNumber of times this form was filled.
records[{form_index}].group_idGroup ID in which this form is.
records[{form_index}].fieldsContains field objects.
records[{form_index}].fields[{field_index}]Field at a given index.
records[{form_index}].fields[{field_index}].field_idField ID.
records[{form_index}].fields[{field_index}].labelText label of form field.
records[{form_index}].fields[{field_index}].answersList of answer objects.
records[{form_index}].fields[{field_index}].answers[{answer_index}]Answer at a given index.
records[{form_index}].fields[{field_index}].answers[{answer_index}].answer_idAnswer ID.
records[{form_index}].fields[{field_index}].answers[{answer_index}].labelText label of answer.
records[{form_index}].fields[{field_index}].answers[{answer_index}].countNumber of times this answer was selected for this field.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/forms \
  -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": "form-report",
	"records": [
		{
			"form_id": "163654772984908812",
			"count": 5,
			"group_id": 0,
			"fields": [
				{
					"field_id": "163654772984903574",
					"label": "Question:",
					"answers": [
						{
							"answer_id": 0,
							"label": "First answer",
							"count": 3
						},
						{
							"answer_id": 1,
							"label": "Second answer",
							"count": 2
						}
					]
				}
			]
		}
	]
}

Response Time

Shows the average agents' response time within a licence.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/chats/response_time
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.countThe total number of chats that day.
records.day.response_timeThe average chat response time for that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/response_time \
  -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": "response-time-report",
	"total": 39,
	"records": {
		"2021-04-08": {
			"count": 3,
			"response_time": 14.22
		},
		"2021-04-09": {
			"count": 4,
			"response_time": 41.35
		},
		"2021-04-10": {
			"count": 3,
			"response_time": 10.1
		},
		"2021-04-11": {
			"count": 9,
			"response_time": 3.34
		},
		"2021-04-12": {},
		"2021-04-13": {
			"count": 5,
			"response_time": 8.5
		},
		"2021-04-14": {},
		"2021-04-15": {
			"count": 6,
			"response_time": 32.3
		}
	}
}

First Response Time

Shows the average agents' first response time within a licence.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/chats/first_response_time
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.countThe total number of chats that day.
records.day.first_response_timeThe average chat first response time for that day.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/chats/first_response_time \
  -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": "first-response-time-report",
	"total": 39,
	"records": {
		"2021-04-08": {
			"count": 3,
			"first_response_time": 14.22
		},
		"2021-04-09": {
			"count": 4,
			"first_response_time": 41.35
		},
		"2021-04-10": {
			"count": 3,
			"first_response_time": 10.1
		},
		"2021-04-11": {
			"count": 9,
			"first_response_time": 3.34
		},
		"2021-04-12": {},
		"2021-04-13": {
			"count": 5,
			"first_response_time": 8.5
		},
		"2021-04-14": {},
		"2021-04-15": {
			"count": 6,
			"first_response_time": 32.3
		}
	}
}

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.5/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.5/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
		}
	}
}

Performance

Shows the total number of agent's chats, the number of good and bad rates they received, and how well they performed in the early stages of a chat. Additionally, the report shows the time an agent spent chatting, accepting and not accepting chats, as well as the total time they were logged in.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/agents/performance
HTTP methodPOST, GET
Required scopesreports_read
Request

See available parameters and filters.

Response
FieldNotes
summarySummary for all agents.
summary.chats_countThe total number of chats the agents had in the specified period of time.
summary.chats_rated_goodThe number of chats rated good.
summary.chats_rated_badThe number of chats rated bad.
summary.first_response_chats_countThe total number of chats in which the agents have replied to the first message sent by the customers.
summary.first_response_timeThe average time in seconds the agents took to send a first reply to the customers' messages.
recordsContains the agent objects.
records.chats_countThe total number of chats the agent had in the specified period of time.
records.chats_rated_goodThe number of agent's chats rated good.
records.chats_rated_badThe number of agent's chats rated bad.
records.first_response_chats_countThe number of chats where the agent has replied to the first message sent by the customer.
records.first_response_timeThe average time in seconds the agent took to send a first reply to the customers' messages.
records.accepting_chats_timeThe time in seconds during which the agent had the accepting_chats status set.
records.chatting_timeThe time in seconds during which the agent was chatting.
records.logged_in_timeThe time in seconds during which the agent was logged in.
records.not_accepting_chats_timeThe time in seconds during which the agent had the not_accepting_chats status set.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/agents/performance \
  -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": "performance-report",
	"records": {
		"smith@example.com": {
			"accepting_chats_time": 35296,
			"chats_count": 4,
			"chats_rated_bad": 0,
			"chats_rated_good": 2,
			"chatting_time": 55,
			"first_response_chats_count": 3,
			"first_response_time": 9.666666666666666,
			"logged_in_time": 45304,
			"not_accepting_chats_time": 10008
		},
		"agent@example.com": {
			"accepting_chats_time": 24567,
			"chats_count": 13,
			"chats_rated_bad": 3,
			"chats_rated_good": 5,
			"chatting_time": 275,
			"first_response_chats_count": 8,
			"first_response_time": 8.133333,
			"logged_in_time": 32110,
			"not_accepting_chats_time": 7543
		}
	},
	"summary": {
		"chats_count": 17,
		"chats_rated_bad": 3,
		"chats_rated_good": 7,
		"first_response_chats_count": 11,
		"first_response_time": 8.55151490909091
	}
}

Tags

Chat Usage

Shows the total number of chats marked with each tag listed in the report.

Specifics
Method URLhttps://api.livechatinc.com/v3.5/reports/tags/chat_usage
HTTP methodPOST, GET
Required scopesreports_read
Request
ParameterRequiredData typeNotes
timezoneNostringIANA Time Zone (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, filters.from is parsed to get it.
filtersNoobjectIf none provided, your report will span the last seven days.
filters.fromNostringFilters out chats that took place within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.toNostringFilters out chats that took place within the time range defined as <from,to>. Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.groups.valuesNo[]intArray of group IDs.
Response
FieldNotes
recordsContains the <tag>:<chat_count> pairs.
REQUEST
Copied!
curl -X POST \
https://api.livechatinc.com/v3.5/reports/tags/chat_usage \
  -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",
      "groups": {
        "values": [ 0, 42 ]
      }
    }
  }'
Response
Copied!
{
	"name": "tags-chat-usage-report",
	"records": {
		"docs_feedback": 4,
		"spam": 3,
		"support": 3
	}
}

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

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@livechat.com