tg_support_bot

Telegram-бот для автоматизации приёма и обработки обращений в техническую поддержку внутри компании.

🚀 Возможности

• Авторизация сотрудников по корпоративному email (с проверкой по белому списку)
• Автоматическое добавление новых email-адресов с возможностью блокировки
• Интерфейс выбора категории обращения через Telegram-клавиатуру
• Ввод текста обращения и отправка в Telegram-группу и/или на email
• Поддержка состояний, шаблонов и персонализированных сообщений
• Гибкая настройка поведения через YAML-файлы
• Использование Jinja2 для генерации текста и HTML-писем
• Логирование в файл и консоль

Алгоритм работы бота

Бот работает как конечный автомат (FSM) с пошаговой логикой обработки пользователей. Вот краткое описание его работы:

1. ▶️ Запуск и команда /start

• Пользователь запускает бота командой /start.
• Бот проверяет, авторизован ли пользователь по Telegram ID.

---

2. 🔐 Авторизация по email

• Если пользователь не авторизован, бот просит ввести корпоративный email.
• Если включено allow_incomplete_input, то email можно вводить без домена (например, ivanov → ivanov@yourcompany.com).
• Email проверяется:
  • по регулярному выражению (email_pattern),
  • на наличие в белом списке (таблица email-ов в БД),
  • на отсутствие блокировки (is_banned).

Возможные сценарии:

• ✅ Email найден и не заблокирован → авторизация, переход к следующему шагу.
• ⛔ Email не найден → бот уведомляет, что email не зарегистрирован.
• 🚫 Email заблокирован → бот уведомляет и не авторизует пользователя.

---

3. 🔄 Повторная авторизация

Если пользователь уже авторизован:

• При повторном вводе того же email — бот сообщает, что авторизация уже выполнена.
• При вводе нового email — бот просит подтвердить смену email.

---

4. 👋 Приветствие и ввод обращения

• После успешной авторизации бот может (в зависимости от настроек):
  • отправить приветствие (welcome_user.txt),
  • предложить выбрать категорию обращения.

---

5. ℹ️ Выбор категории

• Пользователь выбирает тему обращения (например, «Программные ошибки»).
• Используется inline-клавиатура с категориями из ticket_categories.

---

6. 💬 Ввод сообщения

• Бот просит ввести текст обращения.
• Проверяется длина (если превышает max_submission_length, сообщение отклоняется).
• Проверяется частота обращений (max_requests в interval_sec).

---

7. 📤 Отправка обращения

• Бот формирует текст обращения на основе шаблонов (ticket_summary.txt, support_email.html).
• Отправляет обращение в:
  • указанный Telegram-чат (SUPPORT_CHAT_ID),
  • email (через SMTP-параметры из .env).

---

8. 🔁 Возврат в IDLE

• После отправки бот переходит в состояние IDLE, ожидая новых команд или запросов от пользователя.

📦 Установка

Убедитесь, что у вас установлен Python 3.9 или выше.

1. Клонируйте репозиторий:

   git clone https://github.com/yourname/tg_support_bot.git
   cd tg_support_bot

2. Создайте и активируйте виртуальное окружение:

   python -m venv venv
   call venv\Scripts\activate  # Windows
   source venv/bin/activate    # Linux/macOS

3. Установите зависимости:

   pip install -r requirements.txt

Или просто запустите:

setup.bat

▶️ Запуск

Для запуска Telegram-бота:

start_bot.bat      # Windows
./start_bot.sh     # Linux/macOS

Для тестовой отправки email:

start_test_email.bat

⚙️ Конфигурационные файлы

.env

В файле .env указываются ключевые параметры:

BOT_TOKEN=your_bot_token
EMAIL_SENDER=bot@yourcompany.com
EMAIL_PASSWORD=app_password
SMTP_SERVER=smtp.yourcompany.com
SMTP_PORT=587
SUPPORT_EMAIL=support@yourcompany.com
SUPPORT_CHAT_ID=-1001234567890
LOG_LEVEL=DEBUG

Пояснения к параметрам

Переменная	Назначение
BOT_TOKEN	Токен Telegram-бота от @BotFather.
EMAIL_SENDER	Адрес email-отправителя (например, корпоративный ящик бота).
EMAIL_PASSWORD	Пароль/токен приложения для SMTP-аутентификации отправителя.
SMTP_SERVER	SMTP-сервер, используемый для отправки email-сообщений.
SMTP_PORT	Порт SMTP-сервера (обычно 587 для STARTTLS или 465 для SMTPS).
SUPPORT_EMAIL	Email службы поддержки — указывается в уведомлениях и шаблонах.
SUPPORT_CHAT_ID	Telegram chat ID (например, группы) для пересылки тикетов.
LOG_LEVEL	Уровень логирования: DEBUG, INFO, WARNING, ERROR, CRITICAL.

config/auth.yaml

Файл auth.yaml управляет поведением авторизации пользователей через email. Он используется в логике обработки команды /start и ввода email в Telegram-боте.

Пример конфигурации

auth:
  email_pattern: "^[a-zA-Z0-9_.+-]+@yourcompany\.com$"
  email_autocomplete: "@yourcompany.com"
  allow_incomplete_input: true
  send_welcome_before_topic: true
  send_topic_after_auth: true
  delay_after_auth_success: 2

Пояснения к параметрам

Параметр	Тип	Описание
email_pattern	string	Регулярное выражение, задающее допустимый формат email. Используется для валидации введённого email. Например, можно разрешить только домен @yourcompany.com.
email_autocomplete	string	Суффикс, который будет автоматически добавлен к email, если пользователь ввёл только логин без @. Например, foo превратится в foo@yourcompany.com.
allow_incomplete_input	boolean	Разрешить ли автоматическое дополнение email при неполном вводе (например, test → test@yourcompany.com). Если false, то пользователь обязан вводить полный email.
send_welcome_before_topic	boolean	Если true, то перед показом выбора категории обращения будет отправлено приветственное сообщение.
send_topic_after_auth	boolean	Управляет тем, будет ли показан выбор категории сразу после успешной авторизации. Если false, бот перейдёт в состояние ожидания и не будет предлагать выбрать тему.
delay_after_auth_success	int	Задержка (в секундах) перед отправкой выбора темы после авторизации. Может использоваться, если нужно дать время на отображение других сообщений (например, приветствия).

config/ui_config.yaml

Файл конфигурации интерфейса содержит параметры управления ботом, в том числе:

• команды меню,
• начальное поведение при авторизации,
• категории тикетов,
• ограничения.

Конфигурация интерфейса:

telegram_menu: # Описывает команды, отображаемые в меню Telegram:
  - command: start
    description: "Обратиться за помощью"
  - command: help
    description: "Показать справку"
  - command: myid
    description: "Показать ID и email (если есть)"

telegram_start: # Параметры поведения после авторизации
  show_action_button_if_authorized: true      # Показывать кнопку действий после входа
  action_button_text: "📨 Отправить обращение" # Текст на этой кнопке

authorization: # Конфигурация авторизации и отображения статусов
  confirm_change_buttons:
    yes: "✅ Да" # Кнопка подтверждения смены email
    no: "❌ Нет" # Кнопка отмены смены email

  email_status_labels:
    allowed: "✅ Разрешён" # Метка для разрешённого email
    banned: "🚫 Забанен"   # Метка для забаненного email

ticket_categories: # Список категорий, которые пользователь может выбрать при создании обращения
  - "💻 Аппаратные сбои"
  - "🛠 Программные ошибки"
  - "🌐 Сетевые проблемы"
  - "🔑 Запросы на доступ"
  - "🛡 Кибербезопасность"
  - "❗ Жалоба/Благодарность"
  - "📁 Другое"

message_limits: # Ограничения по обращениям и текстам
  max_submission_length: 1500   # Максимально допустимая длина одного текстового обращения
  max_requests: 3               # Сколько обращений разрешено в пределах одного периода
  interval_sec: 3600            # Продолжительность периода в секундах (например, 1 час = 3600)

📁 Шаблоны сообщений

Файлы шаблонов находятся в папке templates/. Они позволяют гибко кастомизировать текст сообщений:

Файл	Назначение
auth_start.txt	Приветствие при входе, если пользователь не авторизован
auth_success.txt	Уведомление об успешной авторизации
auth_already.txt	Пользователь уже авторизован
auth_not_registered.txt	Email не найден в базе
auth_banned.txt	Email в базе, но помечен как заблокированный
auth_invalid.txt	Введён некорректный email
auth_change_confirm.txt	Подтверждение смены email
auth_changed.txt	Уведомление об успешной смене email
auth_change_cancelled.txt	Смена email отменена
welcome_user.txt	Приветствие для авторизованного пользователя
select_topic.txt	Выбор категории обращения
select_topic_intro.txt	Вводное сообщение при выборе темы, если кнопка была нажата не по inline-кнопке
enter_message.txt	Просьба ввести текст обращения
invalid_topic.txt	Ошибка при вводе некорректной категории
invalid_input.txt	Введено что-то не по формату/не в нужный момент
message_too_long.txt	Сообщение слишком длинное
ticket_sent.txt	Подтверждение успешной отправки обращения
ticket_summary.txt	Итоговое сообщение, отправляемое в Telegram и/или email
email_added.txt	Успешное добавление email
email_banned.txt	Успешная блокировка email
email_removed.txt	Успешное удаление email
email_required.txt	Email не указан при вызове команды
email_status_found.txt	Статус указанного email (разрешён/забанен)
email_status_not_found.txt	Email не найден
email_subject.txt	Тема письма при отправке email в техподдержку
my_id.txt	Сообщение с ID пользователя и email (если есть)
not_authorized.txt	Ошибка: команда доступна только администраторам
help_user.txt	Справка для обычных пользователей
help_admin.txt	Справка для администраторов
support_email.html	HTML-шаблон email сообщения для поддержки
rate_limit_exceeded.txt	Сообщение о превышении лимита обращений, включает таймер ожидания

Запуск через pyproject.toml

Если используется pyproject.toml, доступен CLI:

tg-support-bot

Лицензия

MIT License