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

For a detailed description of API endpoints, request parameters, response formats, returned errors, see the following specifications:

• Reporter API for getting statistics and generating reports.
• Async API for getting asynchronous responses.

Authorization

Issue a unified token in the API access section. Specify it as a bearer token in your requests.

note

Token for the previous version methods (/reporter/p/{token}…) can still be obtained in the project settings: → Project properties → API tokens tab. However, such tokens are not compatible with the new version.

How to use

Get sessions for the selected period

The POST /reporter/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/2024 to 02/21/2024.
• 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": "2024-02-14T21:00:00.234Z",
      "to": "2024-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

Additional session parameters

You can pass arbitrary parameters from the session to statistics for further analytics. To do this, use the $analytics.setSessionData method:

$analytics.setSessionData("Parameter", "Value")

To retrieve the passed additional parameters, specify the query parameter needToReturnSessionData=true in the request to the POST /reporter/sessions/filter method. The session information in the response contains the parameters:

"sessions": [
    {
        "sessionId": "…",
        …
        "sessionData": {
            "Parameter": "Value"
        },
        …
    }
]

Get message statuses

The POST /reporter/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/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 method starts report generation in asynchronous mode and returns requestId. To track the status and download the generated report, use the GET /api/v1/async/events method, which supports long polling.