# Свой Telegram-бот, который отвечает отчетом

Отчет нужен на ходу, а не после входа в очередной дашборд. Отправьте боту CSV прямо из чата — в ответ придут доля опоздавших ответов и HTML-отчет с графиками категорий и списком обращений. Команда `/last` вернет предыдущую сводку.

![HTML-отчет, который собрал обработчик CSV](/assets/images/telegram-report-preview-7af71117613a487664891b53fd472a52.png)

[Скачать проект и пример CSV](/example-assets/telegram-report.zip) · Ключ LLM не нужен · Работает на шаблоне `telegram-bot`

В проекте только код самого бота: обработчик, отчет, настройки и тесты. Все остальное — прием вебхуков, повторы, порядок сообщений в чате, состояние диалога — выполняет шаблон `telegram-bot`, а разворачивает бота Claude Code с навыком `manage-telegram-bot` из плагина Just Run.

## Что понадобится[​](#prerequisites "Прямая ссылка на Что понадобится")

* Claude Code с плагином Just Run, [установленным и подключенным к аккаунту](/skills.md).
* Права на создание секретов, автоматизаций и одной песочницы из шаблона `telegram-bot`.
* **Новый тестовый бот** от [@BotFather](https://t.me/BotFather).

Если тариф не позволяет будить приостановленную песочницу входящим сообщением, навык предупредит об этом и оставит бота работать постоянно; тогда он считается работающей песочницей.

## Токен остается на платформе[​](#secret "Прямая ссылка на Токен остается на платформе")

Claude не видит токен бота. Его сохраняете вы:

1. Откройте *Секреты* → *Новый секрет* → *Окружение* и назовите секрет `tg-report-bot`.
2. Добавьте `TELEGRAM_BOT_TOKEN` с токеном от BotFather.
3. Добавьте `TELEGRAM_WEBHOOK_SECRET` и нажмите *Сгенерировать* рядом со значением.
4. Нажмите *Создать секрет*.

Второе значение — проверочный ключ вебхука: Just Run сверяет его в каждом апдейте от Telegram, поэтому чужие запросы до бота не доходят. Не вставляйте токен в чат; если это случилось, отзовите его в @BotFather командой `/revoke` и сохраните новый в секрет.

## Запуск[​](#run "Прямая ссылка на Запуск")

Распакуйте `telegram-report`, откройте папку в Claude Code и попросите:

```
Разверни этот проект как Telegram-бота report-bot. Секрет бота — tg-report-bot.
```

Claude проверит, что в секрете есть оба ключа, создаст с ним песочницу и покажет список файлов, которые собирается отправить. После вашего подтверждения он загрузит их через `tar` и `curl` по одноразовой ссылке. В песочнице `jr-bot deploy` отберет файлы, запустит тесты проекта, активирует бота и проверит, что он отвечает. Затем Claude создаст автоматизацию для вебхука, подключит к ней Telegram и назовет `@username` бота.

Если тесты не прошли, бот не активируется, а Claude получит вывод тестов. Релиз будет отклонен, если среди файлов окажутся ключи доступа, базы данных или строка, похожая на токен бота.

## Что получится[​](#result "Прямая ссылка на Что получится")

1. Откройте **личный чат** с ботом и отправьте команду `/start`.
2. Загрузите тестовый файл `support-tickets.csv` как документ.
3. Бот вернет готовый файл `support-report.html`. Ожидаемая статистика внутри: *44 tickets · 40 measured responses · 11 late (27.5%)*.
4. Отправьте команду `/last`, чтобы получить ту же сводку без повторной загрузки файла.

Скриншот выше собран локально тем же кодом, а не в интерфейсе реального Telegram-бота.

## Как адаптировать[​](#customise "Прямая ссылка на Как адаптировать")

Отчет собирается в `services/report.py`, работа с Telegram — в `handlers/report.py`, а `tests/test_report.py` проверяет диалог на приложенном CSV. Тесты запускаются только в песочнице, при развертывании. Попросите Claude о конкретном изменении — категории вашей команды, колонки вашей выгрузки, — а затем:

```
Обнови report-bot.
```

Новая версия сначала проходит тесты в песочнице; если они не прошли, продолжает работать текущая. Обновление сохраняет сводки, адрес вебхука и проверочный ключ.

Обработчик читает CSV в оперативной памяти и хранит только последнюю сводку для каждого чата; Telegram и платформа хранят свою историю отдельно. Если бот упадет сразу после отправки ответа, ответ может прийти повторно — строгой гарантии доставки ровно один раз нет. Если тариф позволяет будить бота, его песочница приостанавливается после пяти минут простоя, и следующий апдейт ее будит; первый ответ после паузы приходит дольше.

## Диагностика и удаление[​](#troubleshooting "Прямая ссылка на Диагностика и удаление")

Попросите Claude показать `статус report-bot`. Не будя бота, он покажет его состояние и последние запуски: в выводе каждого видно, обработан ли апдейт, пропущен или упал, с классом ошибки, но без текста сообщений. `Подробный статус` разбудит бота и дополнительно проверит вебхук в Telegram, а `логи report-bot` покажут журнал бота.

Когда закончите, попросите Claude `удалить report-bot`. Он назовет песочницу и автоматизации, которые удалит, и дождется вашего подтверждения. Затем уберет вебхук (если тот все еще указывает на этого бота), автоматизации и песочницу вместе с сохраненными сводками. Секрет останется: удалите `tg-report-bot` в разделе *Секреты*, если он больше не нужен. Сам бот в Telegram и уже отправленные файлы останутся в Telegram.

**Дальше:** [запускайте задачу по расписанию, без сообщения в чат](/examples/run-a-scheduled-job.md).
