Chime Reporting API

Written By Instant Support

Updated 10/26/2023 - Our Chime reporting API has been made available as part of our chat based SaaS service desk application. Information is available on our latest product page where we consolidate information on reporting.

Overview

We are providing a reporting API to Chime so that our partners, as well as our internal developers, can access Chime metrics and reporting for external dashboards, scheduled report collection, or other reasons.

Currently, we don't have a good way to automate generating reports in Chime. Somebody must log into the web portal with a browser, and manually download each report that is desired. This reporting API should solve many recent enhancement requests in this area.

API Keys

Initially we considered just using a single global API key, but decided that having per-user keys is better, for several reasons:

  • All of our reports have ACLs controlling what data they show, per user. Admins see everything, but if you aren't an admin, you could be scoped as a manager for one or more queues, and so you'd only be able to pull details for those queues.

  • All of our logging of HTTP requests assumes that there is an authenticated user, and to some degree, this is a primitive audit log where you can see what users are making what requests.

  • If there's one API key for the whole system, if you need to invalidate it for some reason and create a new one, then you have to touch everything that is using it. If you set up different jobs to use different user keys, then there is some separation.

The API keys that we have settled on using are very simple - it's just a GUID that is associated with a user, which is used as a authorization bearer token header on requests to the reporting API.

Creating an API Key for a User

To create an API key for a user, you'll need to find the user in the Admin/People section.

If they don't have an API key created already, clicking the big green button will generate one.

1.png

After the key is created, it will be displayed here, along with the time it was created.

If you click the Generate Key button again, it will prompt to make sure you want to invalidate the old key and generate a new one.

If you click the Generate Key button again, it will prompt to make sure you want to invalidate the old key and generate a new one.

Viewing Granted API Keys

In the Admin/Settings section, there is a new tab titled API Keys.

This has a table showing all of the API keys that have been created and the users they are issued for.

Items.png

Using the API Key to Make a Request

All of the Chime reports follow the same API scheme. There are three parts to take note of:

  1. The URL for the report - each report has a different API route which is based on the name of the report (See more below)

  2. The query string parameters

  3. For requests using the API key, the Authorization header.

Getting Session Details (Added in Build: 3.1.578)

We have added a new API route to get session details for a specific chat using the same API key used to gather reports.

Report URLs

Every Chime report has a specific API route. These are subject to change, and we're always adding more, so the best way to discover these is through the API that the Chime UI itself uses.
(Links below are not real, merely to show the construction of the full URLs)

Items.png

There is one data object per report.

  • Controller - This is the relative API route to the report. To construct the full URL, it is necessary to add the https://example.com/Chime base path, e.g. https://example.com/Chime/Report/BotChatDetails

  • Title - This is the name of the report, as used elsewhere in Chime.

  • ChartType - Internal use for the Chime UI, specifying how the chart should be rendered on the portal.

  • Category - Internal use for the Chime UI, specifying groupings of reports

  • StartOnly - Some reports only cover a single day, and so only support a start date parameter

Query String Parameters

  • start - This is the start of the time interval for the report, this should be an ISO-8601 date/time string

  • end - This is the end of the time interval for the report, also should be an ISO-8601 date/time string

  • csv csv=true will return the report data as CSV, otherwise the report is returned in the format expected by the charting engine used by the Chime Web UI, which is cumbersome.

  • queueId - For queue-level reports, the ID of the queue must be supplied. For global reports, this can be omitted.

  • zone - By default, all date/time fields in reports are returned in UTC time. If a timezone name (see https://nodatime.org/TimeZones ) is passed in this parameter, the date/time values in the data will be adjusted to the specified timezone. e.g. &zone=America%2FNew_York converts to US Eastern Time.

Items.png

Authorization Header

Items.png

The request will need to have an authorization header applied, which should be of the format "Bearer {API_KEY}"

Example Code

cURL

curl --location --request GET 'https://example.com/Chime/Report/InboundVsAnsweredChats?queueId=1&start=2020-11-01T04:00:00.000Z&stop=2020-12-01T04:59:59.999Z&csv=true' \
--header 'Authorization: Bearer b5c38d85-a042-4cef-8418-eb06752e346b'

JQuery

```js
var settings = {
  "url": "https://example.com/Chime/Report/InboundVsAnsweredChats?queueId=1&start=2020-11-01T04:00:00.000Z&stop=2020-12-01T04:59:59.999Z&csv=true",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer b5c38d85-a042-4cef-8418-eb06752e346b"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
```

NodeJS

```js
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://example.com/Chime/Report/InboundVsAnsweredChats?queueId=1&start=2020-11-01T04:00:00.000Z&stop=2020-12-01T04:59:59.999Z&csv=true',
  'headers': {
    'Authorization': 'Bearer b5c38d85-a042-4cef-8418-eb06752e346b'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```
Instant Support
Previous

How to create a Microsoft Teams HTML button?
Next

Chime Deflection: Collect Additional Info During Deflection