# Approach for JSON vs XLSX/CSV

The common `historical-metrics` endpoint has a limitation where the JSON `/data` response is limited to 10,000 records. The XLSX/CSV download available at `historical-metrics/detailed-report` does not have this limitation.

To overcome this limitation the `historical-metrics/detailed-report` endpoint is available to allow for consumers to access JSON format data for large result sets expected with detailed reports.

Requirement: for CSV/XLSX content

Leverage the `historical-metrics` endpoint. CSV/XLSX is not available via `historical-metrics/detailed-report`

Strong Recommendation: for JSON content

Leverage the `historical-metrics/detailed-report` endpoint and the result set won't be limited to 10,000 records.

This guarantees a full result set regardless of the size of the response.

You will need a working API key to begin

ο»Ώ[How to get API Keys](πŸ”—ο»Ώ)ο»Ώ

The base URL is region specific, based on the location of your Contact Center tenant.

  • United States: `https://api.8x8.com/analytics/cc/{version}/historical-metrics/`

  • Europe: `https://api.8x8.com/eu/analytics/cc/{version}/historical-metrics/`

  • Asia-Pacific: `https://api.8x8.com/au/analytics/cc/{version}/historical-metrics/`

  • Canada: `https://api.8x8.com/ca/analytics/cc/{version}/historical-metrics/`

  • {version} to be replaced by current Version. As of June 2023 this is <<versionCCAHistorical>> resulting in /v<<versionCCAHistorical>>/

# 1. Authenticate to retrieve access token

ο»Ώ[OAuth Authentication for 8x8 XCaaS APIs](πŸ”—ο»Ώ) is used to get a temporary `access_token` for use in with this API

**Outputs For Next Step:**

  • access_token

  • expires_in

The following steps will use the access_token as a Bearer Token form of authentication. This takes the form of the `Authorization` header being set to `Bearer access_token` (Space between Bearer and the access_token)

# 2 Multitenancy support

If the API is used for a multitenant customer the requests should contain _"X-Tenant-Info"_ header variable where needs to specify the desired tenantId. The "X-Tenant-Info" header is not mandatory in case of a single tenant customer.

The following error messages could be returned when dealing with a multitenant customer:

  • if for a multitenant customer request the _"X-Tenant-Info"_ header is not provided the HTTP 400 code along with _"Bad request: X-Tenant-Info header is missing."_ message will be returned

  • if a wrong tenantId is provided the HTTP 400 code along with _"Bad request: Invalid value for X-Tenant-Info header."_ message will be returned

# 3. Get Available Report Types

CC Historical Analytics allows the consumer to get a listing of the available reports including information about their options and available data.

Available Detailed Reports

Currently `detailed-reports-interaction-details` and `detailed-reports-agent-status-change` are the available detailed reports.

Additional information about each of the reports and detailed definitions of metrics can be found in the [Interaction Details report - Glossary](πŸ”—ο»Ώ) and [Agent Status Change Detail](πŸ”—ο»Ώ)ο»Ώ

## Parameters

**Method: GET**

### Headers

NameRequiredDescriptionExample
Authorizationβœ“Pass the access_token returned from the authentication request as a Bearer token `Bearer {access_token}`Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

### Path

NameRequiredDescriptionExample
versionβœ“The current version is `v<<versionCCAHistorical>>`v<<versionCCAHistorical>>ο»Ώ
report-type☐Specific report type to get information on. Omit this parameter to get all report types.agent-status-by-status-code

ο»Ώ[API reference](πŸ”—ο»Ώ)ο»Ώ

## Report Types Request

The response shows each `report-type` that's available.

ο»Ώ

## Report Types Response

The response shows each `report-type` that's available.

**Outputs For Next Step:** For detailed reports the response has a number of elements to guide the usage:

  • `type` each report type has a unique definition

  • `metrics` these are the available metrics for the report type. When creating a report. See the [Interaction Details report - Glossary](πŸ”—ο»Ώ) and [Agent Status Change Detail](πŸ”—ο»Ώ) for additional detail on the definition of the available metrics

    • if no metrics are specified: All metrics will be returned

    • if metrics are specified: ONLY the specified metrics will be returned

  • `searchQuery` Provides information on the searchable fields and the operators for those searches. See [searchQuery](πŸ”—ο»Ώ) below for more detailed description.

    • `fields` field name of searchable field

    • `operators` list of valid operators

Generic Example:

ο»Ώ

**Sample Response for single report type**

ο»Ώ

# 4. Creating a report

This sample is applicable to ALL detailed report types

The values in passed in will be specific to the report-type but the concepts are applicable to all detailed reports.

## Parameters

**Method:** POST

### Headers

NameRequiredDescriptionExample
Authorizationβœ“Pass the access_token returned from the authentication request as a Bearer token `Bearer {access_token}`Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

### Path

NameRequiredDescriptionExample
versionβœ“The current version is `v<<versionCCAHistorical>>`v<<versionCCAHistorical>>ο»Ώ

### Body

NameRequiredDescriptionExample
typeβœ“The report type. Acceptable values are the types returned from the `report-types` APIagent-status-by-status-code
titleβœ“The report title, which allows only the characters listed below: letters from A to Z, a to z, 0 to 9, whitespaces or ! - \_ . \* ' ( ). If the report is later downloaded as a file, the title is used as the filename.agent-status-by-status-code
dateRange.startβœ“This parameter specifies that only events and records on or after the specified date are in the report. The entered values should follow the ISO 8061 standard (YYYY-MM-DDTHH:MM:SS.SSSZ) (For example, 2019-09-01T23:00:00.000Z)ο»Ώ
dateRange.endβœ“This parameter specifies that only events and records on or before the specified date are included in the report. The entered values should follow the ISO 8061 standard. (YYYY-MM-DDTHH:MM:SS.SSSZ) (For example, 2019-09-01T23:00:00.000Z)ο»Ώ
timezone☐The desired timezone (([IANA Time Zones](πŸ”—ο»Ώ). Examples America/New_York, Europe/Helsinki [Wikipedia Time Zone List](πŸ”—ο»Ώ))) that is applicable to current metrics only. Accepted timezone values are those that are configured for the tenant. The value can be the tenant’s default timezone or a value defined as an optional timezone. If no value is specified, the tenant’s default timezone is usedEurope/Helsinki
intraDayTimeRange.start☐See [IntraDayTimeRange](πŸ”—ο»Ώ). The start time for the intraDayTimeRange. The format is hh:mm:ss08:30:00
intraDayTimeRange.end☐See [IntraDayTimeRange](πŸ”—ο»Ώ). The end time for the intraDayTimeRange. The end must be at least 5 minutes after the start. The format is hh:mm:ss17:00:00
metrics☐Can be omitted and all available metrics will be returned, or an array of `metrics` can be specified and only these metrics will be returned. See [metrics](πŸ”—ο»Ώ)ο»Ώ"metrics": [ "accepted", "acceptedInSla", "acceptedInSlaPercentage", "acceptedPercentage", "totalAbandoned", "totalAbandonedPercentage" ]
searchQuery☐ See [searchQuery](πŸ”—ο»Ώ)ο»Ώtrue
includeParticipants☐Only valid for detailed-reports-interaction-details report type. Default is false. see [includeParticipants](πŸ”—ο»Ώ)ο»Ώtrue
reportSettings.showOngoingInteractions☐Allows interactions to be displayed that are not still ongoing and have partial data representing the current state of that interaction.true
reportSettings.showInteractionsStateInTime☐This parameter can be combined with _showOngoingInteractions_ to show interactions as they were when providing a time range not up to the present, showing interactions in the ongoing state for when the time range ends.true

#### intraDayTimeRange

This parameter is used to specify a time range filter which applies within each day of the report. If this parameter is not specified, data will be returned for the complete time frame described in the mandatory dateRange object.

intraDayTimeRange minimum size

The _end_ must be 5 minutes after the start for detailed reports and 15 minutes after the start for summary reports.

  • _start_: the start time for the intraDayTimeRange. The format is hh:mm:ss

  • _end_: the end time for the intraDayTimeRange. The format is hh:mm:ss

If the requirement is to only see data between 8:30am and 5pm on each day the intraDayTimeRange would be passed as follows

ο»Ώ

#### metrics

can be omitted and all available metrics will be returned, or an array of `metrics` can be specified and only these metrics will be returned.

Metrics Example

If the requirement is to only have a subset of the the available metrics for the report type, we specify the required metrics

  • if no metrics are specified (omitted entirely or empty array): All metrics will be returned

  • if metrics are specified: ONLY the specified metrics will be returned

ο»Ώ[Interaction Details report - Glossary](πŸ”—ο»Ώ) and [Agent Status Change Detail](πŸ”—ο»Ώ) provide detail on the definitions of the available metrics

ο»Ώ

#### searchQuery

This parameter can be completely omitted Or an empty array can be passed to signify no filter.

searchQuery logical operation.

The searchQuery object is an array which can include one or several objects, each acting as a filter containing the fields: field, operator, and value. If multiple filter objects are specified, the relation between them is logical AND

searchQuery operators are type specific

  • Numeric Fields ( durations like `busyDuration` and counts like `warmTransfersCompleted`:

    • `=, <, >, !=, >=, <=, is-empty, is-not-empty`

    • for durations (like `participantWrapUpDuration`, `ivrTreatmentDuration`) 1s => 1 second, 10m => 10 minutes, 3h => 3 hours, 7d => 7 days

  • Id fields (like `interactionId`) and names (like `queueName`) `contains, is-empty, is-not-empty`

Sample Search Queries (click for details)

ο»Ώ

## Create Report Request

In this example we are running the report from 3rd August to 2nd September, we are only interested in the periods between 8:30am and 5pm on each day. The data returned will only be where agentNotes contains "order" and queueName is "US Sales" or "EU Sales" and the ivrTreatementDuration was greater than or equal to 10 seconds.

ο»Ώ

## Create Report Response:

For an accepted request to create a report the response will be 200 OK

### Headers

  • **Link**: The Link header will provide details on how to access the data

ο»Ώ

Successful Creation always results in DONE

There is no need to poll for status with detailed reports, this is a variation from summary reports.

### Body

  • **id**: this is the identifier for the generated report

  • **status**: this is the status of the request for a newly created report.

    • DONE : the report has been generated

    • FAILED : the report has failed to generate

ο»Ώ

# 5. Accessing Report Data

Accessing the report Data

The data is available via JSON ONLY from `historical-metrics/detailed-reports`

CSV/XLS responses are available from the `historical-metrics` endpoint use the [CC Historical Analytics Summary Report](πŸ”—ο»Ώ) process for CSV/XLSX output of detailed reports

## Parameters

**Method:** GET

### Headers

NameRequiredDescriptionExample
Authorizationβœ“Pass the access_token returned from the authentication request as a Bearer token `Bearer {access_token}`Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

### Path

NameRequiredDescriptionExample
versionβœ“The current version is `v<<versionCCAHistorical>>`v<<versionCCAHistorical>>ο»Ώ
report-idβœ“Report id to get data for2853641

### Query

NameRequiredDescriptionExample
size☐The number of records to return in each page. Default is 100. Maximum is 1000100
lastDocumentId☐/βœ“This MUST BE OMITTED in the request for the initial page. Then the value MUST BE PASSED in subsequent requests See [Headers & Pagination](πŸ”—ο»Ώ) for more informationagent-status-by-status-code

## Report Data Request

ο»Ώ

## Report Data Response

### Headers & Pagination

  • **Link**: The Link header will provide a link to the next page in the data if there are additional pages by using the lastDocumentId to index into the result set `<https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/detailed-reports/2710192/data?size=3&lastDocumentId=eyJzZWFyY2hBZnRlciI6WzE2NDQ0NzA0MzQ5NzIsOTQ1MDExNzMwMjhdfQ%3D%3D>; rel="next"`

  • **X-Page-Size**: size of the requested pages

  • **X-Total-Pages**: total number of pages for the report, 1 if only one page.

  • **X-Total-Elements**: total number of elements for the report

  • **Last-Document-Id**: the id of the last record in this page. Input to subsequent request to get the next page.

**Pagination**

When requesting the first page the `lastDocumentId` **MUST BE OMMITTED**

When requesting subsequent pages use the returned value of the Last-Document-Id header in as the `lastDocumentId` of the following request. The Last-Document-Id will change on each request.

When the last page is reached:

  • `Link` Header will not be present

  • `Last-Document-Id` Header will not be present

### Body

The body will be an array as shown below.

  • The array could be empty if there are no records in the result

  • If not empty the array will contain one or more objects as described here - **total**: is `null` for detailed reports - **items**: array of the dimensions and metrics being returned. There will be one object for each. - _key_: the value will be the name of the dimension/metric - _label_: the value will be the human friendly name of the dimension/metric - _value_: the value will be the value of the dimension/metric. The value could be a string, could represent an array of values (ex. _["Queued", "Handled" ]_) or an object.

The _finishedTime_ metric has the following format:

ο»Ώ

The following duration metrics have the bellowed format :

_queueWaitDuration, ivrTreatmentDuration, interactionDuration, customerJourneyDuration, participantOfferDuration, participantHandlingDuration, participantWrapUpDuration, participantProcessingDuration, participantBusyDuration, participantHoldDuration, participantLongestHoldDuration, participantMuteDuration, participantMuteHoldDuration_

ο»Ώ

where the `value` field is the value of the metric itself, could be represented as a time format in case of _finishedTime_ metric and as milliseconds for the rest of the above duration metrics. The `ongoing` field shows if the value is on its final state (_=false_) or the value could still be changed since the interaction is still ongoing (_=true_).

To get also the ongoing interactions the _reportSettings.showOngoingInteractions_ request parameter should be set to _true_, otherwise the ongoing interactions will not be returned and the _ongoing_ metric field will always be _false_.

Sample example response:

ο»Ώ

#### includeParticipants

When _detailed-reports-interaction-details_ report type is created with _includeParticipants_ =`true` flag, the report response return also the `participants` field which contains the following participant metrics:

  • `blindTransferToAgent`

  • `blindTransferToQueue'`

  • `conferencesEstablished`

  • `consultationsEstablished`

  • `participantAssignNumber`

  • `participantBusyDuration`

  • `participantHandlingDuration`

  • `participantHandlingEndTime`

  • `participantHold`

  • `participantHoldDuration`

  • `participantId`

  • `participantLongestHoldDuration`

  • `participantName`

  • `participantOfferAction`

  • `participantOfferActionTime`

  • `participantOfferDuration`

  • `participantOfferTime`

  • `participantProcessingDuration`

  • `participantType`

  • `participantWrapUpDuration`

  • `participantWrapUpEndTime`

  • `warmTransfersCompleted`

  • `wrapUpCode`

  • `wrapUpCodeId`

  • `wrapUpCodeList`

  • `wrapUpCodeListId`

  • `wrapUpCodeText`

  • `wrapUpShortCode`

Sample response when includeParticipants is true

ο»Ώ