Документация
Компоненты
- Сбор сообщений из групповых чатов MAX (бот — администратор чата)
- SQLite: сообщения, чаты, настройки, админы, ключевые слова
- GigaChat: формирование краткого саммари по каждому чату
- APScheduler: отправка дайджеста по расписанию
- FastAPI: webhook в production, long polling в разработке
Переменные окружения (.env)
| Переменная | Назначение |
|---|
| MAX_BOT_TOKEN | Токен бота (business.max.ru → Чат-боты → Интеграция) |
| SUMMARY_RECIPIENT_USER_ID | user_id получателя дайджеста в ЛС |
| GIGACHAT_CREDENTIALS | Ключ GigaChat (developers.sber.ru) |
| GIGACHAT_MODEL | Модель, например GigaChat |
| BOT_MODE | polling или webhook |
| WEBHOOK_URL | Публичный HTTPS URL /webhook (production) |
| WEBHOOK_SECRET | Секрет для заголовка X-Max-Bot-Api-Secret |
| WEBHOOK_PORT | Локальный порт, по умолчанию 8080 |
config.yaml
| Параметр | Значение |
|---|
| digest.time | Время отправки дайджеста (HH:MM, Europe/Moscow) |
| digest.period | previous_day — вчера 00:00–24:00; current_day — с 00:00 сегодня |
| digest.include_empty_chats | true/false — включать чаты без сообщений |
| trigger_mode | reply_in_chat / notify_owner / both |
| keywords | Список word + template для автоответов |
CLI
python run.py run
python run.py run --ngrok
python run.py digest
python run.py digest --today
python run.py digest --yesterday
python run.py backfill
Production
- BOT_MODE=webhook, WEBHOOK_USE_NGROK=false
- Указать WEBHOOK_URL и WEBHOOK_SECRET
- HTTPS:443 → localhost:WEBHOOK_PORT (nginx/caddy)
- docker compose up -d или systemd unit deploy/max-summary-bot.service
- Том ./data для SQLite
Health
GET /health — проверка работы сервиса
Инструкция пользователя
Роли
| Роль | Действия |
|---|
| Администратор бота | Настройка через ЛС, добавление бота в группы, ключевые слова |
| Получатель дайджеста | Ежедневно получает AI-сводку по всем чатам в ЛС |
| Участник группы | Пишет сообщения; при ключевом слове — автоответ или уведомление |
Первый запуск (администратор)
- Заполнить .env: MAX_BOT_TOKEN, SUMMARY_RECIPIENT_USER_ID, GIGACHAT_CREDENTIALS
- Настроить config.yaml: время дайджеста, period, trigger_mode, keywords
- Добавить бота администратором во все нужные групповые чаты
- Запустить бота: python run.py run
- Выполнить python run.py backfill — подтянуть сообщения за вчера
- Открыть бота в ЛС — должно появиться меню с кнопками
Ежедневный дайджест (получатель)
- Приходит автоматически в digest.time (часовой пояс Europe/Moscow)
- Формат: дата → блоки по каждому чату с AI-резюме
- Если сообщений не было — уведомление «за день не было сообщений»
- Ручная отправка (админ/CLI): python run.py digest, --today, --yesterday
Ключевые слова (участники групп)
- Срабатывание: подстрока в тексте, без учёта регистра
- reply_in_chat — бот отвечает в чат шаблоном (reply)
- notify_owner — уведомление получателю в ЛС
- both — оба действия
- Повтор того же слова в том же чате блокируется на 5 минут
Примеры слов: проблема, срочно, ошибка, не работает, заявка, жалоба, возврат, оплата, доставка, помощь
Админ-панель (кнопки в ЛС)
| Кнопка | Действие |
|---|
| Статус | Режим, webhook, число чатов, ключевые слова, время дайджеста, получатель |
| Дайджест | Сменить время (HH:MM), период (previous_day / current_day) |
| Триггеры | Режим: ответ в чате / уведомление / оба |
| Ключевые слова | Просмотр, добавление (слово + шаблон), удаление |
| Получатель | Задать user_id получателя дайджеста |
| Админы | Добавить/удалить администраторов |
| Обновить | Обновить главное меню |
После смены времени дайджеста — перезапуск бота (расписание читается при старте).
Добавление бота в новый чат
- Добавить бота администратором в группу
- Бот отправит приветствие о подключении
- Чат попадёт в базу, новые сообщения сохраняются
Устранение неполадок
| Проблема | Решение |
|---|
| Дайджест пустой | Проверить, что бот был админом в нужный день; выполнить backfill |
| Webhook не работает локально | VPN для ngrok; python run.py run --ngrok |
| GigaChat недоступен | Дайджест уйдёт с fallback — список сообщений без AI |
| Нет доступа к админке | Попросить админа добавить ваш user_id |
| Доступ запрещён | Ваш user_id не в списке администраторов |
Безопасность
- Не передавать .env и токены третьим лицам
- При утечке MAX_BOT_TOKEN — перевыпустить на business.max.ru
- Webhook защищён заголовком X-Max-Bot-Api-Secret