Reporter API

Reporter API — это API для продвинутого управления аналитикой проектов.

Методы Reporter API позволяют:

• Получать сводную статистику по обзвонам, уникальным пользователям и диалогам, переведенным на оператора.
• Получать расширенную статистику по количеству сообщений, сессий и установленных меток.
• Получать список клиентов, а также блокировать или разблокировать их.
• Получать список сообщений по определенным сессиям или клиентам.
• Проставлять, удалять, получать метки сообщений и сессий.
• Создавать, активировать, завершать и удалять эксперименты, а также подсчитывать количество сессий, задействованных в экспериментах.
• Создавать отчеты по сессиям, сообщениям, клиентам и обзвонам, а также удалять задачи на генерацию отчетов.

подсказка

Методы, параметры запросов, форматы ответов, возвращаемые ошибки подробно описаны в спецификациях:

• Reporter API — получение статистики, формирование отчетов.
• Async API — получение асинхронных ответов.

Авторизация

Выпустите единый токен в разделе Доступ к API. Указывайте его в запросах как bearer-токен.

примечание

Для методов предыдущей версии Reporter API (/reporter/p/{token}…) получение токена по-прежнему доступно в настройках проекта: → Свойства проекта → вкладка API-токены. Однако такие токены не подходят для методов новой версии.

Примеры использования

Получение сессий за определенный период

Метод POST /reporter/sessions/filter позволяет получить сессии за определенный период времени.

Допустим, мы хотим получить информацию о сессиях, в которых:

• Сообщения были получены за неделю с 14.02.2024 по 21.02.2024.
• Отсутствуют пустые сессии.
• Количество полученных сообщений варьируется от 20 до 50.

В таком случае в теле запроса установим фильтры MESSAGE_TIME, WITHOUT_EMPTY_SESSIONS и MESSAGE_COUNT следующим образом:

{
  "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"
    }
  ]
}

В ответе запроса получим подробную информацию об отфильтрованных сессиях:

• ID сессии
• Тип канала
• ID, фамилии и имена клиентов
• Начало и длительность сессий
• Первая и последняя фразы
• Количество сообщений
• Проставленные метки

Дополнительные параметры сессии

Вы можете передавать из сессии произвольные параметры в статистику для дальнейшей аналитики. Для этого используйте метод $analytics.setSessionData:

$analytics.setSessionData("Параметр", "Значение")

Чтобы получить переданные дополнительные параметры, при вызове метода POST /reporter/sessions/filter укажите query-параметр needToReturnSessionData=true. Информация о сессии в ответе будет содержать эти параметры:

"sessions": [
    {
        "sessionId": "…",
        …
        "sessionData": {
            "Параметр": "Значение"
        },
        …
    }
]

Получение статусов сообщений

Метод POST /reporter/messages/by-session позволяет получить статусы сообщений в каналах Telegram, Viber и ВКонтакте.

Статусы сообщений возвращаются в поле status. Возможные значения:

• SENT — отправлено;
• NOT_SENT — не отправлено;
• DELIVERED — доставлено;
• NOT_DELIVERED — не доставлено;
• READ — прочитано.

подсказка

Статус SENT можно получить только в каналах Telegram и ВКонтакте, а статус READ — в Viber и ВКонтакте.

Создание отчета по сообщениям

Метод POST /reporter/reports/messages позволяет создать отчет по сообщениям.

Чтобы создать отчет по сообщениям, полученным только в канале Telegram за все время, напишите в теле запроса следующее:

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

Метод запускает формирование отчета в асинхронном режиме и возвращает requestId. Чтобы отслеживать готовность и получить отчет, используйте метод GET /api/v1/async/events, который поддерживает long polling.