Skip to main content

Reporter API

Tovie Platform provides the Reporter API for advanced project analytics management.

The Reporter API methods allow:

  • Receiving summary statistics on calls, unique users, and dialogs transferred to the agent.
  • Getting advanced statistics on the number of messages, sessions, and labels set.
  • Getting client lists, as well as blocking or unblocking them.
  • Getting a list of messages for specific sessions or clients.
  • Adding, deleting, and getting message and session labels.
  • Creating, activating, ending, and deleting experiments, as well as counting the number of sessions involved in experiments.
  • Generating reports on sessions, messages, clients, and calls, as well as deleting tasks for report generation.
tip
A detailed description of the Reporter API: methods, request parameters, response formats, examples, returned errors

Get API token​

tip
Before you start working with the Reporter API, you need to obtain a unique token that will be used in method requests.
  1. To obtain a token, open a project for which you want to get analytics.
  2. Click and select Project properties.
  3. In the pop-up window, open the API tokens tab and click . The token will be copied to the clipboard.
  4. Substitute the token parameter in the request string with the copied token.

How to use​

Get sessions for the selected period​

The POST /reporter/p/{token}/sessions/filter method allows receiving all sessions for the selected time period.

For example, you want to get information about sessions in which:

  • Messages were received within one week from 02/14/2021 to 02/21/2021.
  • There are no empty sessions.
  • The number of received messages varies from 20 to 50.

In this case, specify the MESSAGE_TIME, WITHOUT_EMPTY_SESSIONS, and MESSAGE_COUNT filters in the request body.

{
  "filters": [
    {
      "key": "MESSAGE_TIME",
      "type": "DATE_TIME_RANGE",
      "from": "2021-02-14T21:00:00.234Z",
      "to": "2021-02-21T20:59:59.000Z"
    },
    {
      "key": "WITHOUT_EMPTY_SESSIONS",
      "type": "RADIO",
      "option": "YES"
    },
    {
      "key": "MESSAGE_COUNT",
      "type": "NUMERIC_RANGE",
      "from": "20",
      "to": "50"
    }
  ]
}

The request’s response will contain information about filtered sessions such as:

  • Session ID
  • Channel type
  • Clients ID, first and last names
  • Session start time and duration
  • The first and last phrases
  • Message count
  • Labels

Get message statuses​

The POST /reporter/p/{token}/messages/by-session method allows you to get message statuses in Telegram, Viber, and VK channels.

The response will contain the status in the status field. The following message statuses are supported:

  • SENT
  • NOT_SENT
  • DELIVERED
  • NOT_DELIVERED
  • READ
tip
The SENT status is only available in Telegram and VK and the READ status is in Viber and VK.

Generate a message report​

The POST /reporter/p/{token}/reports/messages method allows generating a message report.

For example, to generate a report on messages received only in the Telegram channel, write the following in the request body:

{
  "filters": [
    {
      "key": "CHANNEL_TYPE",
      "type": "CHECKBOX",
      "options": [
        "telegram"
      ]
    }
  ],
  "settings": {
    "fileType": "XLSX",
    "withHeader": true
  }
}

The generated message report will be available for downloading on the Background tasks tab.