TelegramSupportBot — лёгкий Telegram-бот поддержки на Python и Aiogram 3. Он принимает обращения пользователей, группирует сообщения в тикеты, уведомляет администратора после короткой паузы и даёт отвечать прямо из Telegram-панели без отдельной CRM.
- Создаёт тикеты автоматически: если у пользователя нет открытого обращения, первое сообщение создаёт новый тикет.
- Использует настраиваемые ID тикетов: по умолчанию тикеты создаются в формате
AA-XXXXXX, а префикс можно поменять черезTICKET_PREFIX. - Показывает название вашего сервиса в приветствии: текст
Привет! Это поддержка ...берёт название изSERVICE_NAME, без хардкода в коде. - Собирает несколько сообщений в одно обращение: бот ждёт паузу
ACK_DELAY, после чего подтверждает пользователю приём заявки и уведомляет администратора. - Сохраняет историю в JSON: тикеты, пользователи и сообщения лежат в простых JSON-файлах.
- Даёт администратору Telegram-панель: можно открыть список тикетов, посмотреть историю, ответить пользователю и закрыть обращение.
- Корректно показывает длинные истории: большие карточки тикетов разбиваются на несколько сообщений, чтобы не упираться в лимиты Telegram.
- Передаёт разные типы контента в обе стороны: текст, подписи к медиа, фото, видео, голосовые, документы, аудио, GIF, стикеры, локации, контакты, опросы и dice-сообщения сохраняются в истории; вложения пользователя можно открыть в тикете, а ответы администратора копируются пользователю без скачивания файлов.
- Пользователь пишет боту или отправляет
/start. - В приветствии бот показывает название из
SERVICE_NAME. - При первом сообщении без открытого обращения создаётся тикет с ID вида
<TICKET_PREFIX>-XXXXXX. - Сообщение пользователя добавляется в историю тикета.
- Бот ждёт тишину
ACK_DELAYсекунд, затем отправляет пользователю подтверждение и уведомляет администратора. - Администратор открывает «Панель», выбирает тикет, читает историю и вложения, отвечает текстом или поддерживаемым Telegram вложением либо закрывает обращение.
- После закрытия пользователь может написать снова — будет создан новый тикет.
| Тип | Как отображается в тикете |
|---|---|
| Текст | Оригинальный текст сообщения |
| Медиа с подписью | Тип медиа и подпись; оригинал можно открыть в тикете |
| Голосовое | Длительность и оригинальное вложение |
| Фото | Оригинальное вложение |
| Видео / видео-кружок | Длительность и оригинальное вложение |
| Документ | Имя файла и оригинальное вложение |
| Аудио | Название, длительность и оригинальное вложение |
| GIF / анимация | Оригинальное вложение |
| Стикер | Emoji и оригинальное вложение |
| Локация / место | координаты и ссылка на Google Maps |
| Контакт | имя и телефон |
| Опрос | вопрос и варианты ответа |
| Dice | emoji и выпавшее значение |
| Неизвестный тип | техническое имя типа сообщения |
Бот сохраняет идентификаторы исходного чата и сообщения и использует Telegram
copyMessage: файлы на сервер не скачиваются. Если исходное сообщение удалить до просмотра тикета, Telegram может не позволить скопировать вложение.
bot/
core/
dispatcher.py # регистрация обработчиков
json_storage.py # JSON-хранилище с блокировкой записи
loader.py # Bot и Dispatcher
utils.py # безопасная отправка, длинные сообщения, форматирование контента
handlers/
admin.py # админ-панель, ответы, закрытие тикетов
user.py # приветствие и входящие сообщения пользователей
services/
scheduler.py # отложенное подтверждение и уведомление админа
tickets.py # создание тикетов и история сообщений
users.py # состояние пользователей
config.py # настройки из переменных окружения
example.env # пример .env-конфигурации
requrements.txt # зависимости проекта
python3 -m venv .venv
source .venv/bin/activate
pip install -r requrements.txtСкопируйте пример конфигурации и заполните значения:
cp example.env .envПеременные окружения:
| Переменная | Описание | Пример / значение по умолчанию |
|---|---|---|
BOT_TOKEN |
токен Telegram-бота от BotFather | 123456:ABC... |
ADMIN_ID |
Telegram ID администратора | 123456789 |
SERVICE_NAME |
название сервиса в приветствии пользователя | Example |
TICKET_PREFIX |
префикс ID тикетов перед случайной частью | AA |
ACK_DELAY |
пауза перед подтверждением и уведомлением, сек. | 30 |
USERS_PATH |
путь к JSON-файлу пользователей | data/users.json |
TICKETS_PATH |
путь к JSON-файлу тикетов | data/tickets.json |
MESSAGES_PATH |
папка с историями сообщений | data/messages |
Раньше в приветствии было захардкожено {example}. Теперь название берётся из .env:
SERVICE_NAME=My ServiceПосле этого пользователь увидит:
Привет! Это поддержка My Service.
По умолчанию бот создаёт тикеты с префиксом AA, например AA-7F3A1C. Если нужен другой префикс, укажите его в .env без дефиса:
TICKET_PREFIX=ABНовые тикеты будут создаваться в формате AB-XXXXXX.
python3 bot/main.py- Напишите
/startот имени администратора — бот покажет нижнюю кнопку «Панель». - Нажмите «Панель», чтобы увидеть открытые тикеты.
- Откройте тикет, чтобы посмотреть последние сообщения пользователя.
- Нажмите «Ответить 📩» и отправьте текст, фото, видео, документ, голосовое или другой поддерживаемый Telegram тип сообщения — бот скопирует его пользователю и сохранит описание в истории тикета.
- Если Telegram не смог доставить ответ (например, пользователь заблокировал бота), бот покажет ошибку и оставит режим ответа активным, чтобы сообщение можно было повторить.
- Нажмите «Закрыть ❌», чтобы закрыть тикет и разрешить пользователю создать новый.
Проект использует JSON-файлы и не требует отдельной базы данных:
tickets.jsonхранит список тикетов и их статусы.users.jsonхранит состояние пользователей: текущий тикет, время последнего сообщения, флаги уведомлений.messages/ticket_<ID>.jsonхранит историю конкретного тикета.
Для небольшого саппорта этого достаточно. Если нагрузка вырастет, JSON-хранилище лучше заменить на SQLite или PostgreSQL.
Минимальная проверка синтаксиса:
python3 -m py_compile bot/main.py bot/core/*.py bot/handlers/*.py bot/services/*.py config.pyСм. файл LICENSE.