Бот собирает обращения из клиентских чатов MAX, создаёт заявки в рабочем чате и помогает специалистам назначать, выполнять и закрывать их. Это самостоятельный Python-проект: свои настройки, роли, SQLite-база и история. Telegram-бот работает отдельно; синхронизация и перенос его базы не предусмотрены.
Релиз 1.0.9. Заявки, личное меню сотрудников, массовое закрытие, рассылки с вложениями и таймером, отчёты, расписания, резервное копирование и автоустановка. Набор проверок — 273 теста; схема SQLite — 21. Для первого запуска MAX нужно настроить HTTPS и зарегистрировать Webhook.
- Сбор сообщений клиента во время ожидания ответа специалиста; создание заявки после таймаута.
- Карточки в клиентском и рабочем чатах: взять, отменить, завершить, назначить или переназначить исполнителя.
- Списки заявок, полный сохранённый текст обращения, роли специалистов и администраторов.
- Стоп-слова, настройка времени ожидания, объявления и напоминания по расписанию.
- Общая и личная статистика, Excel-отчёты.
- Сохранение событий до подтверждения Webhook, очередь доставки и ручная сверка неопределённых отправок.
- Установщик с вводом настроек, служба systemd, обновление с резервной копией, ежедневный backup и ручная очистка старых копий.
Для пользователей: руководство пользователя. Для администратора сервера: быстрая установка и полная инструкция Linux.
Установщик рассчитан на Debian 13 или Ubuntu 24.04 с systemd. Нужны sudo/root, доступ к пакетным репозиториям и MAX API, токен бота, ID чата специалистов и MAX ID начального администратора. Клиентские чаты вручную перечислять не нужно. Для получения событий нужны публичный HTTPS и права бота в чатах.
Скопируйте полный проект на сервер и из его каталога запустите:
sudo bash scripts/install.shМастер запросит токен, чаты, роли, время ожидания, часовой пояс, сетевые настройки и секрет Webhook. Он установит зависимости, создаст отдельного пользователя и службу, проверит конфигурацию/API и включит ежедневные резервные копии после пробного копирования.
| Данные | Путь после установки |
|---|---|
| Начальная версия и окружение | /opt/max-ts-ticket-bot |
| Последующие версии | /opt/max-ts-ticket-bot/releases/ |
| Профиль с секретами | /etc/max-ts-ticket-bot/config.json |
| База MAX | /var/lib/max-ts-ticket-bot/max_bot.db |
| Резервные копии | /var/backups/max-ts-ticket-bot/ |
HTTPS и подписка MAX настраиваются отдельно. Установщик не выпускает сертификат и не регистрирует подписку. Пошаговая настройка Nginx, проверка публичного маршрута и регистрация подписки описаны в руководстве установки. Репозиторий: IndeecDen/max_ts_ticket_bot.
Добавьте бота в групповой чат клиентов и отправьте описание проблемы обычным сообщением. В автоматическом режиме любой групповой чат, из которого бот получает события MAX, становится клиентским, кроме WORK_CHAT_ID — чата специалистов. Перезапуск при добавлении в новый чат не требуется. Если специалист не ответит до истечения ожидания, бот сформирует заявку. Управление заявкой доступно через кнопки карточек. Личные диалоги и каналы автоматически не подключаются.
Новый установщик включает этот режим сам. Для существующего профиля задайте в объекте policy поле "auto_client_chats": true, сохраните остальные настройки и перезапустите службу. Старый профиль с непустым client_chats без этого поля продолжит работать по явному списку. Уже обработанные как ignored_chat события автоматически повторно не обрабатываются.
| Команда | Назначение |
|---|---|
/menu, /start, /help |
Личное меню сотрудников и помощь по роли |
/cancel |
Отмена ввода параметров в личном меню |
/whoami |
MAX ID, ID текущего чата и роли бота |
/my_requests |
Свои обращения в текущем клиентском чате |
/request <номер> [страница] |
Сохранённый текст доступного обращения |
/open_requests |
Открытые заявки в рабочем чате |
/open_unassigned_requests |
Заявки без исполнителя |
/my_active_requests |
Заявки текущего специалиста |
/my_stats, /my_stats_xlsx |
Статистика специалиста |
/stats, /stats_xlsx |
Общая статистика для администратора |
Меню доступно только в личном диалоге с ботом специалистам и администраторам. В группах и каналах меню не выводится, у клиентов доступа нет. Роль и принадлежность кнопки пользователю/диалогу проверяются при каждом нажатии; отзыв роли прекращает доступ к старым кнопкам и ожидающему вводу. Роли хранятся в базе: изменение начальных ролей в профиле не заменяет назначение/отзыв через команды бота.
- 📋 Заявки: открытые, неназначенные, свои в работе; страницы кнопками; поиск полного обращения по номеру; взять новую заявку и завершить свою.
- 📊 Статистика: личная, а для администратора также общая; день, последние 7/30 дней или произвольные даты; текст и Excel.
- 👥 Сотрудники — для администратора: список, выдача и отзыв ролей.
- ⚙ Настройки — для администратора: открытые заявки, «🔒 Закрыть все», время ожидания и стоп-слова. Массовое закрытие завершает новые заявки и заявки в работе, показывая их количество; обращения в стадии ожидания сохраняются.
- 📢 Объявления — для администратора: просмотр, добавление, удаление.
- 📣 Рассылки — для администратора: HTML-текст, фото, файлы, видео и аудио с подписью или без неё; предпросмотр и новые кнопки под ним: «Отправить сейчас», «По таймеру», «Отменить». Разовая отправка через число минут или в заданную дату, сохранение после перезапуска, список состояний доставки. Инструкция.
- 🗓 Расписания — для администратора: напоминания о неназначенных заявках, дайджест, автоочистка.
- В разделе заявок администратор также может назначать/переназначать, отменять с причиной и закрывать все активные заявки.
- В меню отображаются сохранённые имена пользователей MAX вместо цифровых ID. Если MAX ещё не прислал имя пользователя, используется нейтральное обозначение; ID остаётся только во вводе команд, где он нужен для однозначного выбора.
После выбора действия бот запрашивает параметры обычным сообщением с примером ввода. Ошибочный ввод можно исправить; /cancel или кнопка отмены возвращают в меню. Ожидающий ввод сохраняется в SQLite, переживает перезапуск и истекает через 15 минут. Переходы обновляют одно сообщение меню; результаты и отчёты отправляются отдельно. На главной странице — число новых, ожидающих и выполняемых заявок. «Чаты бота» удалены. Команды рабочего чата и кнопки карточек заявок продолжают работать.
В чат специалистов поступает карточка с первым сообщением обращения; при наличии вложений пересылается только первое исходное сообщение. Дополнения автора сохраняются в заявке и доступны через /request, но не вызывают отправок или обновления текста карточки. Статусы обновляются в существующей карточке. Очередь приоритетно обрабатывает ответы на кнопки и продолжает готовые отправки между чатами без секундной паузы после каждого задания; ограничения по чатам сохраняются. Исторические ошибки удалённого меню явно помечаются archived_at_ms при миграции, остаются в базе и отдельно учитываются в /readyz как archived_failures.
В личном диалоге администратора: /menu → 📣 Рассылки → ✏ Новая рассылка. Отправьте текст либо вложение с подписью одним сообщением. Проверьте предпросмотр и выберите отправку сейчас, таймер или отмену. Для таймера введите 30 (минут) или 2026-10-15 09:00; часовой пояс показан в меню.
Текст и подпись принимают HTML-теги, например <b>Плановые работы</b>; лимит — 4000 единиц UTF-16, включая теги. Вложения сохраняются по токенам MAX. Неподдерживаемые вложения или отсутствие токена дают ошибку, а не отправку одного текста.
Получатели — известные активные группы, кроме чата специалистов. Диалоги и каналы исключены. Реестр восстанавливается из истории и обновляется по сообщениям и событиям добавления/удаления бота. Для старой группы без сохранённых событий отправьте /whoami непосредственно в ней. Пересылка сообщения в личный диалог группу не регистрирует.
sudo systemctl status max-ts-ticket-bot.service
sudo journalctl -u max-ts-ticket-bot.service -n 100 --no-pager
sudo systemctl restart max-ts-ticket-bot.service
systemctl list-timers max-ts-ticket-bot-backup.timerДля обновления запустите из каталога новой версии проекта:
sudo bash scripts/update.shОбновление готовит отдельное окружение, останавливает службу, сохраняет проверенную копию и переключает версию. При ошибке запуска база автоматически не откатывается. Не используйте повторную первоначальную установку для обновления кода.
После обновления административные Python-команды выполняйте из актуального WorkingDirectory службы, используя .venv/bin/python этой версии. Найти каталог:
systemctl show max-ts-ticket-bot.service --property=WorkingDirectory --valueПодробно: обновление, резервные копии, расписание, восстановление и очистка. Копии содержат секреты; ежедневный таймер не удаляет старые комплекты. Очистка сначала показывает кандидатов, применение требует --apply.
Из каталога проекта, с Python 3.12:
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
.\.venv\Scripts\python.exe -W error::ResourceWarning -m unittest discover -s tests -qКопируйте .env.example только при отсутствии своего .env. Для работы с MAX заполните .env локально: MAX_BOT_TOKEN, WORK_CHAT_ID, WEBHOOK_SECRET и необходимые дополнительные настройки. Файл не предназначен для GitHub. Для тестов токен не нужен.
Проверка конфигурации и доступа к API:
.\.venv\Scripts\python.exe -m app.main check-config
.\.venv\Scripts\python.exe -m app.main check-apiДля полного режима замените все примерные ID своими:
.\.venv\Scripts\python.exe -m app.main run --specialist=99 --bot-admin=77Без --client-chat включается автоматический режим. Для старого режима можно явно передать --client-chat=<ID> несколько раз; --auto-client-chats явно включает автоматический выбор. Для нескольких сотрудников повторяйте соответствующий флаг. Запускайте один экземпляр run. Он принимает Webhook, обрабатывает сохранённые события и выполняет реальные отправки, включая ранее накопленные задания. Без публичного HTTPS и подписки MAX входящие события из мессенджера не поступят.
| Режим/маршрут | Назначение |
|---|---|
run |
Приём событий, обработка и доставка |
serve |
Только сохранение входящих событий |
process-inbox |
Обработка сохранённых событий, без отправки |
deliver-outbox |
Отправка доступных заданий очереди |
queue-status |
Состояние очереди |
/webhook/max |
POST событий с проверкой секрета |
/healthz |
Доступность HTTP-процесса |
/readyz |
Локальная готовность; в run ожидается mode: bot |
При работающем run отдельные обработчики и доставка не требуются. /readyz не подтверждает работоспособность публичного HTTPS или права в MAX.
При создании новой заявки в рабочий чат пересылается только первое исходное сообщение, если оно содержит вложения; исходный JSON сохраняется. Скачивание и повторная загрузка при отказе пересылки не реализованы. Подробности и ограничения вложений. Личные диалоги без chat_id и автоматическая замена удалённых карточек требуют дальнейшей работы. Пошаговый ввод параметров реализован в личном меню сотрудников.
Неопределённые отправки (uncertain) и отправки, прерванные аварией (sending), требуют ручной сверки. Автоматический повтор может создать дубли; гарантии «ровно один раз» между SQLite и MAX нет. failed также требует разбора. При этих проблемах /readyz может возвращать 503.
Работа службы, обновление с сохранением данных и проверка резервных копий подтверждены на Debian 13. Чистая установка Ubuntu 24.04, полное восстановление и перезагрузка ОС требуют отдельных испытаний. При развёртывании настройте сертификат и публичный Webhook, проверьте права бота, события, кнопки и XLSX в своих чатах MAX.
- Релиз 1.0.9: состав, обновление и проверки
- Массовые рассылки: текст, вложения и таймер
- История релизов
- Установка, HTTPS и подписка MAX
- Обновление и резервные копии
- GitHub Actions и локальные проверки
- Архив первоначального плана и этапов
- История разработки и подробные примеры команд частей 1–26
CI настроен на Python 3.12/3.13 и Ubuntu/Windows, с отдельной проверкой Bash и шаблонов systemd. Результаты запуска проверяйте во вкладке Actions репозитория. История разработки сохранена отдельно; её промежуточные статусы не описывают текущее состояние проекта.