Обзор
Система поддержки работает в трёх режимах, задаваемых переменной SUPPORT_SYSTEM_MODE:
| Режим | Описание |
|---|
tickets | Только тикет-система |
contact | Только ссылка на контакт (SUPPORT_USERNAME) |
both | Тикеты + ссылка на контакт (по умолчанию) |
Тикеты для пользователей
Создание тикета
- Пользователь нажимает “Поддержка” в главном меню
- Выбирает “Создать тикет”
- Вводит заголовок (5-255 символов)
- Вводит описание (10-500 символов) или отправляет фото с подписью
- Тикет создаётся со статусом
open и приоритетом normal
- Администратор получает уведомление
У пользователя может быть только один активный тикет (открытый или отвеченный). Для создания нового необходимо закрыть текущий.
Просмотр тикетов
- Мои тикеты — список открытых/отвеченных тикетов с пагинацией (10 на страницу)
- Закрытые тикеты — отдельная вкладка с историей
- Детальный просмотр с историей сообщений (разбивка по 3500 символов на страницу)
- Кнопка “Вложения” для просмотра фото (отправляются как медиагруппа)
Ответ на тикет
- Текст 5-400 символов или фото с подписью
- При ответе пользователя статус меняется на
open
- Антиспам: 1 сообщение в 2 секунды, подавление дублей после создания (6 сек)
Закрытие тикета
Пользователь может закрыть свой тикет в любой момент. История сообщений сохраняется (только чтение).
Статусы и приоритеты
Статусы тикетов
| Статус | Описание |
|---|
open | Открыт, ожидает ответа администратора |
answered | Администратор ответил, ожидает реакции пользователя |
pending | В обработке |
closed | Закрыт |
Приоритеты
| Приоритет | Описание |
|---|
low | Низкий |
normal | Обычный (по умолчанию) |
high | Высокий |
urgent | Срочный |
Администрирование тикетов
Просмотр
- Два раздела: Открытые (open + answered) и Закрытые
- Список с пагинацией (10 на страницу)
- Каждый тикет показывает: статус, приоритет, имя пользователя, username, Telegram ID
- Детальный просмотр с историей сообщений и ссылками на профиль пользователя
Действия администратора
| Действие | Описание |
|---|
| Ответить | Текст до 400 символов или фото. Статус → answered. Пользователь получает уведомление |
| Закрыть | Закрытие тикета. Действие логируется |
| Закрыть все | Массовое закрытие всех открытых/отвеченных тикетов |
| Блокировка (временная) | Блокировка ответов на N минут (1 — 525 600 = 1 год) |
| Блокировка (постоянная) | Постоянная блокировка ответов пользователя |
| Разблокировка | Снятие любой блокировки |
support_audit_logs).
SLA-система
SLA-мониторинг проверяет тикеты без ответа администратора и отправляет уведомления при нарушении.
Как работает
- Фоновая задача проверяет тикеты через заданный интервал
- Если тикет со статусом
open не получил ответа дольше, чем SLA_MINUTES — отправляется уведомление
- Повторные напоминания отправляются с учётом cooldown
- При ответе пользователя таймер SLA сбрасывается
Настройка
| Переменная | По умолчанию | Описание |
|---|
SUPPORT_TICKET_SLA_ENABLED | false | Включить SLA-мониторинг |
SUPPORT_TICKET_SLA_MINUTES | 60 | Минут до нарушения SLA |
SUPPORT_TICKET_SLA_CHECK_INTERVAL_SECONDS | 300 | Интервал проверки (секунды) |
SUPPORT_TICKET_SLA_REMINDER_COOLDOWN_MINUTES | 30 | Cooldown между повторными напоминаниями |
Все параметры SLA можно менять в реальном времени из админ-панели бота или через Cabinet API без перезапуска.
Модераторы
Модераторы — обычные пользователи с ограниченным доступом к тикетам. Управление модераторами доступно из раздела настроек поддержки в админ-панели.
Возможности модераторов
- Просмотр всех тикетов (открытых и закрытых)
- Ответ на тикеты
- Закрытие тикетов (единичное и массовое)
- Блокировка/разблокировка пользователей
- Просмотр вложений
Все действия модераторов логируются в журнал аудита с пометкой is_moderator=True.
Управление
- Добавить модератора — указать Telegram ID
- Удалить модератора — указать Telegram ID
- Список модераторов — показать всех
Модераторы получают отдельную точку входа в интерфейсе бота (кнопка “Тикеты” в панели модератора).
Вложения
Поддерживаются фотографии:
- Пользователи могут прикрепить фото при создании тикета или в ответе
- Администраторы могут отправить фото в ответе
- Фото хранятся как Telegram
file_id
- Просмотр через кнопку “Вложения” — отправляются медиагруппой (до 10 фото)
Уведомления
Тикет-система использует 4 канала уведомлений:
| Канал | Получатель | Триггеры |
|---|
| Telegram (админы) | Чат администраторов | Новый тикет, ответ пользователя, нарушение SLA |
| Telegram (пользователь) | Личный чат пользователя | Ответ администратора |
| Cabinet (БД) | Веб-интерфейс | Все события (с отметками прочитано/непрочитано) |
| WebSocket | Cabinet в реальном времени | Новый тикет, ответы |
Защита от злоупотреблений
- Один активный тикет — нельзя создать новый при наличии открытого
- Глобальная блокировка — заблокированный в любом тикете пользователь не может создавать новые
- Rate limiting — 1 сообщение в 2 секунды (через Redis)
- Защита от дублей — проверка FSM-состояния + подавление на 6 секунд после создания
- Автоудаление сообщений — пользовательские сообщения удаляются через 2 секунды для чистоты чата
Настройки поддержки
Основные переменные
| Переменная | По умолчанию | Описание |
|---|
SUPPORT_USERNAME | @support | Контакт поддержки (username или URL) |
SUPPORT_MENU_ENABLED | true | Показывать меню поддержки |
SUPPORT_SYSTEM_MODE | both | Режим: tickets, contact, both |
Настройки из админ-панели (без перезапуска)
| Настройка | Описание |
|---|
system_mode | Режим поддержки |
menu_enabled | Показывать в главном меню |
support_info_texts | Текст описания поддержки (HTML, по языкам) |
admin_ticket_notifications_enabled | Telegram-уведомления для админов |
user_ticket_notifications_enabled | Telegram-уведомления для пользователей |
ticket_sla_enabled | SLA-мониторинг |
ticket_sla_minutes | Порог SLA |
moderators | Список модераторов |
Уведомления
| Переменная | По умолчанию | Описание |
|---|
ADMIN_NOTIFICATIONS_CHAT_ID | — | Telegram чат для уведомлений |
ADMIN_NOTIFICATIONS_TICKET_TOPIC_ID | — | ID топика для тикетов |
Cabinet и Web API
Тикет-система полностью доступна через Cabinet (веб-интерфейс) и Web API:
- Пользователи: создание тикетов, ответы, просмотр уведомлений (текст до 4000 символов)
- Администраторы: просмотр всех тикетов, ответы, смена статуса/приоритета, статистика
- Web API: полный доступ через токен (статус, приоритет, блокировки, ответы, медиа)
