Skip to content

Latest commit

 

History

History
1001 lines (746 loc) · 53.9 KB

index.mdx

File metadata and controls

1001 lines (746 loc) · 53.9 KB
Raw
weight category subcategory title tagline desc versionGroup apiVersion robots
10
data-reporting
reports-api
Reports API
Access and extract data from Reports.
See how you can access and extract data from Reports with the use of Reports API.
data-reporting
3.6
noindex

import { openChatWindow } from "utils/index";

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.6. 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@text.com or ask on the chat, and we'll give you access. 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.6/reports/<resource>/<action>

Headers

Common headers for all methods:

Header Value Required Notes
Authorization Bearer <token> Yes Your access token
X-API-Version 3.6 No The API version. You can also specify it in the URL.

Additional headers specifically for the POST methods:

Header Value Required
Content-Type application/json Yes

Available methods
Chats duration tags total_chats ratings ranking engagement greetings_conversion forms response_time first_response_time
Agents availability performance
Tags chat_usage

Available parameters and filters

For the Chats reports

Parameter Required Data type Notes
distribution No string Allowed values: hour, day, day-hours, month or year. Defaults to day.
timezone No string IANA 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.
filters No object If none provided, your report will span the last seven days.
filters.from No string Filters 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.to No string Filters 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>1 No any Described below.
filters.agents.<string_filter_type>2 No any Described below; exists set to false will return unassigned chats; true will return the assigned ones.
filters.tags.<string_filter_type>2 No any Described below.
filters.sales.<integer_filter_type>3 No any Described below.
filters.goals.<integer_filter_type>3 No any Described below.
filters.surveys.<survey>4 No array Described below.
filters.event_types.<event_type_filter_type>5 No any Described below.
filters.groups.<integer_filter_type>3 No array Array of group IDs.
filters.greetings.from No string Filters 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.to No string Filters 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>1 No any Described below.
filters.greetings.groups.<integer_filter_type>3 No any Described below.
filters.agent_response.exists No bool
filters.agent_response.first No bool Modifier that makes the other agent_response filters operate exclusively on the agents' first response.
filters.agent_response.agents.<string_filter_type>2 No any Described below. Works only if the agent_response.first filter is set to true.
filters.agent_response.groups.<integer_filter_type>3 No any Described below. Works only if the agent_response.first filter is set to true.
filters.customer_countries.<string_filter_type>2 No any Described 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

Parameter Required Data type Notes
distribution No string Allowed values: hour, day. Defaults to day.
timezone No string IANA 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.
filters No object If none provided, your report will span the last seven days.
filters.from No string Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.to No string Date & time format compatible with RFC3339 with optional resolution of microseconds, YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM.
filters.agents.<string_filter_type>2 No any Described below.
filters.groups.values No array Array 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)

<CodeResponse version="v3.6" type="reports" title={'Sample survey filter'} json="surveyFilter" />

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.

<CodeResponse version="v3.6" type="reports" title={'Sample filters'} json="filters" />

The JSON payload above translates into the following query string:

<CodeSample path={'FILTERS AS QUERY STRING PARAMS'}>

?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 URL https://api.livechatinc.com/v3.6/reports/chats/duration
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

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.agents_chatting_duration The average chat duration agents had that day.
records.day.duration The average chat duration for that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Tags

Shows the distribution of tags for chats.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/tags
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

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>. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Total Chats

Shows how many chats occurred during the specified period.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/total_chats
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

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. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Ratings

Shows the number of rated chats along with their ratings during a specified period of time.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/ratings
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

Response

Field Notes
total The total number of chats in the specified date range.
records Contains the distribution objects, for example, day.
records.day.chats The total number of chats that day.
records.day.bad The number of chats rated bad that day.
records.day.good The number of chats rated good that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Ranking

Shows the ratio of good to bad ratings for each operator.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/ranking
HTTP method POST, GET
Required scopes reports_read

Request

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

Response

Field Notes
records Contains the agent objects.
records.agent.total The total number of chats an agent had in the specified period.
records.agent.good The number of agent's chats rated good.
records.agent.bad The number of agent's chats rated bad.
records.agent.score The agent's score. Read more about how we calculate agent rankings... 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Engagement

Shows the distribution of chats based on engagement during the specified period.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/engagement
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

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.started_by_customer_from_greeting The number of chats from greetings (also knows as targeted messages) that day.
records.day.started_by_customer_without_greeting The number of chats started by a customer that day.
records.day.started_by_agent The number of chats started by an agent that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

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 URL https://api.livechatinc.com/v3.6/reports/chats/greetings_conversion
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

Response

Field Notes
total The total number of chats in the specified date range.
records Contains the distribution objects, for example, day.
records.day.greeting_id.accepted The number of chats started as a result of accepting a greeting that day.
records.day.greeting_id.canceled The number of greetings customers dismissed that day.
records.day.greeting_id.displayed The number of greetings displayed that day.
records.day.greeting_id.goals The number of goals resulted from the greetings that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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]
         }
      }
   }
}'

Forms

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

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/forms
HTTP method POST, GET
Required scopes reports_read

Request

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

Response

Field Notes
records Contains form objects.
records[{form_index}] Form at a given index.
records[{form_index}].form_id Form ID.
records[{form_index}].count Number of times this form was filled.
records[{form_index}].group_id Group ID in which this form is.
records[{form_index}].fields Contains field objects.
records[{form_index}].fields[{field_index}] Field at a given index.
records[{form_index}].fields[{field_index}].field_id Field ID.
records[{form_index}].fields[{field_index}].label Text label of form field.
records[{form_index}].fields[{field_index}].answers List 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_id Answer ID.
records[{form_index}].fields[{field_index}].answers[{answer_index}].label Text label of answer.
records[{form_index}].fields[{field_index}].answers[{answer_index}].count Number of times this answer was selected for this field. 
curl -X POST \
https://api.livechatinc.com/v3.6/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 Time

Shows the average agents' response time within a licence.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/response_time
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

Response

Field Notes
total The total number of chats in the specified date range.
records Contains the distribution objects, for example, day.
records.day.count The total number of chats that day.
records.day.response_time The average chat response time for that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

First Response Time

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

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/chats/first_response_time
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

Response

Field Notes
total The total number of chats in the specified date range.
records Contains the distribution objects, for example, day.
records.day.count The total number of chats that day.
records.day.first_response_time The average chat first response time for that day. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

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 URL https://api.livechatinc.com/v3.6/reports/agents/availability
HTTP method POST, GET
Required scopes reports_read

Request

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

Response

Field Notes
total Total time the chat was available in the specified date range.
records Contains the distribution objects, for example, day.
records.hours The total number of hours the chat was available that day (only for the day distribution).
records.minutes The total number of minutes the chat was available that hour (only for the hour distribution). 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

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 URL https://api.livechatinc.com/v3.6/reports/agents/performance
HTTP method POST, GET
Required scopes reports_read

Request

See available parameters and filters.

Response

Field Notes
summary Summary for all agents.
summary.chats_count The total number of chats the agents had in the specified period of time.
summary.chats_rated_good The number of chats rated good.
summary.chats_rated_bad The number of chats rated bad.
summary.first_response_chats_count The total number of chats in which the agents have replied to the first message sent by the customers.
summary.first_response_time The average time in seconds the agents took to send a first reply to the customers' messages.
records Contains the agent objects.
records.chats_count The total number of chats the agent had in the specified period of time.
records.chats_rated_good The number of agent's chats rated good.
records.chats_rated_bad The number of agent's chats rated bad.
records.first_response_chats_count The number of chats where the agent has replied to the first message sent by the customer.
records.first_response_time The average time in seconds the agent took to send a first reply to the customers' messages.
records.accepting_chats_time The time in seconds during which the agent had the accepting_chats status set.
records.chatting_time The time in seconds during which the agent was chatting.
records.logged_in_time The time in seconds during which the agent was logged in.
records.not_accepting_chats_time The time in seconds during which the agent had the not_accepting_chats status set. 
curl -X POST \
https://api.livechatinc.com/v3.6/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"
    }
  }'

Tags

Chat Usage

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

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/tags/chat_usage
HTTP method POST, GET
Required scopes reports_read

Request

Parameter Required Data type Notes
timezone No string IANA 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.
filters No object If none provided, your report will span the last seven days.
filters.from No string Filters 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.to No string Filters 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.values No []int Array of group IDs.

Response

Field Notes
records Contains the <tag>:<chat_count> pairs.

<CodeSample path={'REQUEST'}>

curl -X POST \
https://api.livechatinc.com/v3.6/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 ]
      }
    }
  }'

Stats

Visitors

Shows the total number of unique visitors and their page views during a specified period of time.

Specifics
Method URL https://api.livechatinc.com/v3.6/reports/stats/visitors
HTTP method POST, GET
Required scopes reports_read

Request

Parameter Required Data type Notes
timezone No string IANA 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.
filters No object If none provided, your report will span the last seven days.
filters.from No string Filters 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.to No string Filters 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.

Response

Field Notes
summary Summary for all agents
summary.unique_visitors A total number of unique visitors in the specified period of time.
summary.page_views A total number of their page views in the specified period of time.

<CodeSample path={'REQUEST'}>

curl -X POST \
  https://api.livechatinc.com/v3.6/reports/stats/visitors \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
	"filters": {
		"from": "2024-01-01T00:00:00+00:00",
		"to": "2024-01-07T23:59:59+00:00"
	}
}'

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