From 37c68612faad0bc686ce05cec498835147abea7a Mon Sep 17 00:00:00 2001 From: Maciej Szaflik Date: Thu, 3 Oct 2024 16:59:05 +0200 Subject: [PATCH 1/3] documents unique visitors report --- .../responses/customers/uniqueVisitors.json | 7 ++ src/pages/data-reporting/changelog/index.mdx | 3 +- .../data-reporting/reports-api/v3.6/index.mdx | 83 +++++++++++++++++-- 3 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 payloads/data-reporting/v3.6/reports-api/responses/customers/uniqueVisitors.json diff --git a/payloads/data-reporting/v3.6/reports-api/responses/customers/uniqueVisitors.json b/payloads/data-reporting/v3.6/reports-api/responses/customers/uniqueVisitors.json new file mode 100644 index 000000000..cba460866 --- /dev/null +++ b/payloads/data-reporting/v3.6/reports-api/responses/customers/uniqueVisitors.json @@ -0,0 +1,7 @@ +{ + "name": "visitors-report", + "summary": { + "unique_visitors": 4, + "page_views": 23 + } + } diff --git a/src/pages/data-reporting/changelog/index.mdx b/src/pages/data-reporting/changelog/index.mdx index 9d3b34441..d2db2a9bb 100644 --- a/src/pages/data-reporting/changelog/index.mdx +++ b/src/pages/data-reporting/changelog/index.mdx @@ -21,7 +21,8 @@ The developer preview version provides a preview of the upcoming changes to the ## [v3.6] - Developer preview -No changes yet. +- There's a new method, [**Unique visitors**](/data-reporting/reports-api/v3.6/reports/stats/unique_visitors), which shows how many page views and unique visitors there were on the website during the specified period. +- There's a new method, [**Groups**](/data-reporting/reports-api/v3.6/#groups), which shows how many chats were handled by each group during the specified period. ## [v3.5] - 2022-11-23 diff --git a/src/pages/data-reporting/reports-api/v3.6/index.mdx b/src/pages/data-reporting/reports-api/v3.6/index.mdx index be867c231..bdfdb25ff 100644 --- a/src/pages/data-reporting/reports-api/v3.6/index.mdx +++ b/src/pages/data-reporting/reports-api/v3.6/index.mdx @@ -53,11 +53,12 @@ You can authorize your calls to the Reports API using one of the following metho ## Available methods -| | | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Chats** | [`duration`](#duration) [`tags`](#tags) [`total_chats`](#total-chats) [`ratings`](#ratings) [`ranking`](#ranking) [`engagement`](#engagement) [`greetings_conversion`](#greetings-conversion) [`forms`](#forms) [`response_time`](#response-time) [`first_response_time`](#first-response-time) | -| **Agents** | [`availability`](#availability) [`performance`](#performance) | -| **Tags** | [`chat_usage`](#chat-usage) | +| | | +| -------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Chats** | [`duration`](#duration) [`tags`](#tags) [`total_chats`](#total-chats) [`ratings`](#ratings) [`ranking`](#ranking) [`engagement`](#engagement) [`greetings_conversion`](#greetings-conversion) [`forms`](#forms) [`response_time`](#response-time) [`first_response_time`](#first-response-time) [`groups`](#groups) [`queued_visitors`](#queued_visitors) [`queued_visitors_left`](#queued_visitors_left) | +| **Agents** | [`availability`](#availability) [`performance`](#performance) | +| **Tags** | [`chat_usage`](#chat-usage) | +| **Customers** | [`unique_visitors`](#unique_visitors) | ## Available parameters and filters @@ -104,6 +105,15 @@ If filters are provided, they must contain exactly one pair of time-based filter If filters are provided, they must contain exactly one time-based filter (`filters.from/to`). +### For the Customer reports + +| Parameter | Required | Data type | Notes | +| ----------------------------------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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`. | + +If filters are provided, they must contain exactly one time-based filter (`filters.from/to`). + @@ -517,7 +527,7 @@ https://api.livechatinc.com/v3.6/reports/chats/engagement \ ### 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. +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. @@ -934,6 +944,67 @@ https://api.livechatinc.com/v3.6/reports/tags/chat_usage \ +## Stats + +
+ + +### Unique visitors + +Shows the total number of page views and unique visitors for the specified period. + +#### Specifics + +| | | +| ------------------- | ---------------------------------------------------------------- | +| **Method URL** | `https://api.livechatinc.com/v3.6/reports/stats/unique_visitors` | +| **HTTP method** | POST, GET | +| **Required scopes** | `reports_read` | + +#### Request + +| Parameter | Required | Data type | Notes | +| ----------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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` | Reports summary | +| `summary.unique_visitors` | Number of unique visitors | +| `summary.page_views` | Number of page views | + + + + + + + + +```shell +curl -X POST \ +https://api.livechatinc.com/v3.6/reports/stats/unique_visitors \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{ + "filters": { + "from": "2021-04-08T00:00:00-00:00", + "to": "2021-04-15T23:59:59-00:00", + } + }' +``` + + + + + + + +
+ # Contact us If you found a bug or a typo, you can create an issue on [GitHub](https://github.com/livechat/livechat-public-docs/). In case of any questions or feedback, don't hesitate to contact us at [developers@text.com](mailto:developers@text.com) From 6a1e35101b6955c2a29c0cd28cb90c4369790215 Mon Sep 17 00:00:00 2001 From: Maciej Szaflik Date: Fri, 4 Oct 2024 09:11:04 +0200 Subject: [PATCH 2/3] document group report --- .../reports-api/responses/chats/groups.json | 20 +++++++ .../data-reporting/reports-api/v3.6/index.mdx | 54 +++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 payloads/data-reporting/v3.6/reports-api/responses/chats/groups.json diff --git a/payloads/data-reporting/v3.6/reports-api/responses/chats/groups.json b/payloads/data-reporting/v3.6/reports-api/responses/chats/groups.json new file mode 100644 index 000000000..a673cdeb2 --- /dev/null +++ b/payloads/data-reporting/v3.6/reports-api/responses/chats/groups.json @@ -0,0 +1,20 @@ +{ + "name": "groups-report", + "total": 29, + "records": { + "2024-08-20": { + "0": 1, + "2": 1 + }, + "2024-08-21": { + "0": 20, + "1": 2 + }, + "2024-08-22": { + "0": 1, + "1": 2, + "3": 1, + "4": 1 + } + } +} \ No newline at end of file diff --git a/src/pages/data-reporting/reports-api/v3.6/index.mdx b/src/pages/data-reporting/reports-api/v3.6/index.mdx index bdfdb25ff..006a37dcc 100644 --- a/src/pages/data-reporting/reports-api/v3.6/index.mdx +++ b/src/pages/data-reporting/reports-api/v3.6/index.mdx @@ -758,6 +758,60 @@ https://api.livechatinc.com/v3.6/reports/chats/first_response_time \ +
+ + +### Groups + +Shows the total number of chats were handled by each group during the specified period. + +#### Specifics + +| | | +| ------------------- | ------------------------------------------------------------ | +| **Method URL** | `https://api.livechatinc.com/v3.6/reports/chats/groups` | +| **HTTP method** | POST, GET | +| **Required scopes** | `reports_read` | + +#### Request + +See [available parameters and filters](#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.group` | Contains the `:` pairs. | + + + + + + +```shell +curl -X POST \ +https://api.livechatinc.com/v3.6/reports/chats/groups \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{ + "distribution": "day", + "filters": { + "from": "2024-08-20T00:00:00-00:00", + "to": "2024-08-22T23:59:59-00:00" + } + }' +``` + + + + + + + +
+ ## Agents
From 4adeaf77699d0ec9006a4f15ecacb106f9c1940c Mon Sep 17 00:00:00 2001 From: Maciej Szaflik Date: Fri, 4 Oct 2024 15:29:03 +0200 Subject: [PATCH 3/3] queue visitors reports --- .../responses/chats/queueVisitorsLeft.json | 32 +++ .../responses/chats/queuedVisitors.json | 35 ++++ src/pages/data-reporting/changelog/index.mdx | 2 + .../data-reporting/reports-api/v3.6/index.mdx | 197 ++++++++++++++++++ 4 files changed, 266 insertions(+) create mode 100644 payloads/data-reporting/v3.6/reports-api/responses/chats/queueVisitorsLeft.json create mode 100644 payloads/data-reporting/v3.6/reports-api/responses/chats/queuedVisitors.json diff --git a/payloads/data-reporting/v3.6/reports-api/responses/chats/queueVisitorsLeft.json b/payloads/data-reporting/v3.6/reports-api/responses/chats/queueVisitorsLeft.json new file mode 100644 index 000000000..4d2b747dc --- /dev/null +++ b/payloads/data-reporting/v3.6/reports-api/responses/chats/queueVisitorsLeft.json @@ -0,0 +1,32 @@ +{ + "name": "queued-visitors-left-report", + "total": 2, + "summary": { + "left_without_details": 2, + "total_pages": 1 + }, + "records": { + "SK0P33W2ZJ": { + "visitor": { + "id": "0f864f86-556e-46a9-848e-d2d5fe0a8fe0", + "ip": "169.50.11.126" + }, + "queue": { + "duration": 123, + "group": 0, + "start_date": "2024-10-01T20:47:07Z" + } + }, + "SK0Q3SGMBN": { + "visitor": { + "id": "04e8c9b6-8dc3-4067-a749-0ef983f99e6d", + "ip": "169.50.11.126" + }, + "queue": { + "duration": 21, + "group": 6291, + "start_date": "2024-10-02T18:56:47Z" + } + } + } +} \ No newline at end of file diff --git a/payloads/data-reporting/v3.6/reports-api/responses/chats/queuedVisitors.json b/payloads/data-reporting/v3.6/reports-api/responses/chats/queuedVisitors.json new file mode 100644 index 000000000..48b39bf3c --- /dev/null +++ b/payloads/data-reporting/v3.6/reports-api/responses/chats/queuedVisitors.json @@ -0,0 +1,35 @@ +{ + "name": "queued-visitors-report", + "total": 15, + "records": { + "2024-10-01": { + "left_queue": { + "count": 13, + "min": 0, + "max": 100, + "avg": 20.5384615384615383 + }, + "queued": { + "count": 13, + "min": 0, + "max": 20, + "avg": 2.5384615384615383 + } + }, + "2024-10-02": { + "left_queue": { + "count": 2, + "min": 0, + "max": 3, + "avg": 0.21311475409836064 + }, + "queued": { + "count": 2, + "min": 1, + "max": 10, + "avg": 5.523131672597864 + } + }, + "2024-10-03": {} + } +} \ No newline at end of file diff --git a/src/pages/data-reporting/changelog/index.mdx b/src/pages/data-reporting/changelog/index.mdx index d2db2a9bb..b111d3303 100644 --- a/src/pages/data-reporting/changelog/index.mdx +++ b/src/pages/data-reporting/changelog/index.mdx @@ -23,6 +23,8 @@ The developer preview version provides a preview of the upcoming changes to the - There's a new method, [**Unique visitors**](/data-reporting/reports-api/v3.6/reports/stats/unique_visitors), which shows how many page views and unique visitors there were on the website during the specified period. - There's a new method, [**Groups**](/data-reporting/reports-api/v3.6/#groups), which shows how many chats were handled by each group during the specified period. +- There's a new method, [**Queued visitors**](/data-reporting/reports-api/v3.6/#queued_visitors), which shows how many customers were waiting in the queue during the specified period. +- There's a new method, [**Queued visitors left**](/data-reporting/reports-api/v3.6/#queued_visitors_left), which shows what customers left the queue during the specified period. ## [v3.5] - 2022-11-23 diff --git a/src/pages/data-reporting/reports-api/v3.6/index.mdx b/src/pages/data-reporting/reports-api/v3.6/index.mdx index 006a37dcc..d6bf77455 100644 --- a/src/pages/data-reporting/reports-api/v3.6/index.mdx +++ b/src/pages/data-reporting/reports-api/v3.6/index.mdx @@ -91,6 +91,12 @@ You can authorize your calls to the Reports API using one of the following metho 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`). +Additional parameter for the `queued-visitors-left` method: + +| Parameter | Required | Data type | Notes | +| ----------------------------------------------------- | -------- | --------- | ---------------------------------------------------------------| +| `page` | No | `int` | Non-negative integer allows to paginate products (default: `1`)| + ### For the Agents reports | Parameter | Required | Data type | Notes | @@ -812,6 +818,197 @@ https://api.livechatinc.com/v3.6/reports/chats/groups \
+
+ + +### Groups + +Shows the total number of chats were handled by each group during the specified period. + +#### Specifics + +| | | +| ------------------- | ------------------------------------------------------------ | +| **Method URL** | `https://api.livechatinc.com/v3.6/reports/chats/groups` | +| **HTTP method** | POST, GET | +| **Required scopes** | `reports_read` | + +#### Request + +See [available parameters and filters](#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.group` | Contains the `:` pairs. | + + + + + + +```shell +curl -X POST \ +https://api.livechatinc.com/v3.6/reports/chats/groups \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{ + "distribution": "day", + "filters": { + "from": "2024-08-20T00:00:00-00:00", + "to": "2024-08-22T23:59:59-00:00" + } + }' +``` + + + + + + + +
+ +
+ + +### Queued Customers + +Shows how many customers were waiting in the queue during the specified period. + +#### Specifics + +| | | +| ------------------- | ------------------------------------------------------------ | +| **Method URL** | `https://api.livechatinc.com/v3.6/reports/chats/groups` | +| **HTTP method** | POST, GET | +| **Required scopes** | `reports_read` | + +#### Request + +See [available parameters and filters](#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.left_queue` | Contains informations about customers that have left queue without starting a chat. | +| `records.day.left_queue.count` | Count of customers. | +| `records.day.left_queue.min` | Minium time in second spent in queue. | +| `records.day.left_queue.max` | Maximum time in second spent in queue. | +| `records.day.left_queue.avg` | Average time in second spent in queue. | +| `records.day.queued` | Contains informations about customers that have been in queue and stated a chat. | +| `records.day.queued.count` | Count of customers. | +| `records.day.queued.min` | Minium time in second spent in queue. | +| `records.day.queued.max` | Maximum time in second spent in queue. | +| `records.day.queued.avg` | Average time in second spent in queue. | + + + + + + +```shell +curl -X POST \ +https://api.livechatinc.com/v3.6/reports/chats/queued_visitors \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{ + "distribution": "day", + "filters": { + "from": "2024-10-01T00:00:00-00:00", + "to": "2024-10-03T23:59:59-00:00" + } + }' +``` + + + + + + + +
+ +
+ + +### Queued Customers Left + +Shows what customers left the queue during the specified period. + +#### Specifics + +| | | +| ------------------- | ------------------------------------------------------------ | +| **Method URL** | `https://api.livechatinc.com/v3.6/reports/chats/groups` | +| **HTTP method** | POST, GET | +| **Required scopes** | `reports_read` | + +#### Request + +See [available parameters and filters](#available-parameters-and-filters). + +#### Response + +| Field | Notes | +| --------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `total` | The total number of chats in the specified date range. | +| `summary` | Report summary | +| `summary.left_without_details` | Count of customers with any identifing data. | +| `summary.total_pages` | Total number of pages with customers. | +| `records` | Contains the `customer` objects, unique identifier is chat ID. | +| `records.{chat_id} | Contains informations about customers that have left queue without starting a chat. | +| `records.{chat_id}.prechat_survey | Array of pre-chat survey fields. | +| `records.{chat_id}.prechat_survey.key | Pre-chat survey field key. | +| `records.{chat_id}.prechat_survey.value | Pre-chat survey field value. | +| `records.{chat_id}.prechat_survey.id | Pre-chat survey field ID. | +| `records.{chat_id}.prechat_survey.type | Pre-chat survey field type. | +| `records.{chat_id}.visitor | Customer identifing informations. | +| `records.{chat_id}.visitor.id | Customer uuiq ID. | +| `records.{chat_id}.visitor.name | Customer name set in pre-chat survey. | +| `records.{chat_id}.visitor.email | Customer email set in pre-chat survey. | +| `records.{chat_id}.visitor.ip | Customer IP. | +| `records.{chat_id}.visitor.visitor_custom_variables | Array of custom variables in {key}: {value} format. | +| `records.{chat_id}.queue | Queue data. | +| `records.{chat_id}.queue.duration | How long was queue. | +| `records.{chat_id}.queue.url | At what url queue took place. | +| `records.{chat_id}.queue.group | To what group chat was routed to. | +| `records.{chat_id}.queue.start_date | When queue started. | +| `records.{chat_id}.integration_variables | Array of integration variables in {key}: {value} format. | + + + + + + +```shell +curl -X POST \ +https://api.livechatinc.com/v3.6/reports/chats/queued_visitors_left \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{ + "distribution": "day", + "filters": { + "from": "2024-10-01T00:00:00-00:00", + "to": "2024-10-03T23:59:59-00:00" + } + }' +``` + + + + + + + +
+ ## Agents