Выгрузка отчета по реакциям в Telegram

Вы можете получить детальный отчет по реакциям пользователей на сообщения вашего бота в Telegram. Отчет поможет проанализировать вовлеченность аудитории, оценить отклик на рассылки и ответы бота, а также выявить наиболее популярный контент.

Отчет генерируется асинхронно через Reporter API и выгружается в формате CSV или XLSX.

Доступ к API

Для доступа к API вам понадобится токен:

1. Перейдите в настройки проекта → Доступ к API.
2. Выпустите токен или используйте существующий. В настройках токена должен быть выбран доступ к REPORTER_API.

Подробнее о работе с ключами и доступе к Reporter API (необходимом для получения отчета), смотрите в соответствующем разделе документации.

Получение отчета

Получение отчета состоит из двух шагов:

1. Запуск генерации: вы отправляете POST-запрос с параметрами фильтрации и получаете идентификатор генерации requestId.
2. Получение результата: с помощью requestId вы периодически проверяете статус генерации. Когда отчет будет готов, вы получите ссылку для его скачивания.

Шаг 1. Запуск генерации

Чтобы запустить генерацию отчета, отправьте POST-запрос на эндпоинт:

POST /async/reporter/reports/message-reaction

В теле запроса передайте JSON-объект с параметрами фильтрации, например периодом, за который нужно получить отчет, и форматом отчета (CSV или XLSX).

Пример запроса

curl --request POST 'https://app.jaicp.com/api/v1/async/reporter/reports/message-reaction' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "projectShortName": "mybot-256618725-fuZ-21048053393",
    "botId": "237714518-mybot-256618725-fuZ-21048053393",
    "settings": {
        "format": "XLSX"
    },
    "reactionTimeFrom": 1704067200000,
    "reactionTimeTo": 1706745599000
}'

Пример ответа

В случае успешного запуска вы получите ответ 200 OK. Идентификатор задачи requestId будет находиться в заголовке ответа Z-Request-id. Тело ответа будет пустым.

Если вы планируете получать отчет через API, сохраните значение заголовка Z-Request-id. Он понадобится для проверки статуса задачи на следующем шаге.

Шаг 2. Проверка статуса и получение отчета

Когда отчет будет готов, вы можете получить его двумя способами:

• Через интерфейс JAICP: в проекте появится уведомление о том, что отчет сгенерирован. Вы сможете скачать его прямо из уведомления.

• Через API: чтобы получить отчет через API, с помощью requestId периодически проверяйте статус готовности отчета, отправляя GET-запросы на эндпоинт:

  GET /async/events?requestId={requestId}

Обычно генерация отчета занимает до одной минуты, но в зависимости от объема данных это может занять больше времени.

Пример запроса

curl --request GET \
'https://app.jaicp.com/api/v1/async/events?requestId=a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8' \
--header 'authorizationHeader: YOUR_API_TOKEN'

Формат ответа

Пока отчет генерируется, эндпоинт будет возвращать пустой массив в поле response:

{
    "response": []
}

Вам нужно реализовать периодический опрос (polling): продолжайте отправлять GET-запросы с интервалом (например, раз в 5—10 секунд), пока не получите ответ со статусом COMPLETED.

Когда отчет будет готов, вы получите ответ с данными в поле response:

{
    "response": [
        {
            "isOk": true,
            "requestId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
            "isAsync": true,
            "requestTime": "2025-08-29 09:57:09.039",
            "responseTime": "2025-08-29 09:57:09.757",
            "payload": {
                "taskId": "9ce8ed0c-63cf-43cd-b474-0bb5c84f46f9",
                "accountId": 1000021,
                "creationTime": 1756461429532,
                "status": "COMPLETED",
                "reportType": "MESSAGE_REACTION",
                "settings": {
                    "fileType": "XLSX",
                    "withHeader": true,
                    "delimiter": ",",
                    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                },
                "projectShortName": "mybot-256618725-fuZ-21048053393",
                "writeCount": 3,
                "totalCount": 3,
                "fileName": "message_reaction_1111111-1000001-hjq_2025-08-29",
                "isAdminReport": false,
                "launchCount": 1
            },
            "error": null
        }
    ]
}

Сформируйте ссылку для скачивания отчета, используя данные из поля payload в ответе, по шаблону:

https://<host>/message_reaction/<accountId>/<taskId>/<fileName>.<fileType>

где:

• <host> — хост S3-совместимого хранилища вашей инсталляции:

  • для app.jaicp.com: 56e34b67-1f67-44a2-b7f7-8327872829a2.selstorage.ru.

  • для zb.04: a42deb4-b027-4119-a6ab-96408d179ccd.selstorage.ru.

• <accountId> — значение поля payload.accountId.

• <taskId> — значение поля payload.taskId.

• <fileName> — значение поля payload.fileName.

• <fileType> — расширение файла, указанное в запросе (например, xlsx).

Структура отчета

Готовый файл (CSV или XLSX) будет содержать следующие данные:

Столбец	Описание
Message	Текст сообщения или ссылка на медиафайл, на который была поставлена реакция.
Reaction	Сама реакция (эмодзи) или ее код.
Reaction message ID	Идентификатор сообщения с реакцией.
Message creation date	Дата и время отправки исходного сообщения ботом (UTC).
Reaction creation date	Дата и время постановки реакции (UTC).
Session ID	Идентификатор сессии пользователя, который поставил реакцию.
Sending message IDs	Список всех идентификаторов сообщений из одного ответа бота, например отправленного с помощью $conversationApi. Используется для отладки в редких случаях, когда не удается однозначно определить, на какое именно сообщение была поставлена реакция.