TG Support Bot — Мультиканальная платформа технической поддержки

Телеграм бот для объединения сообщений из Telegram, ВКонтакте, Max и сторонних API источников в единую систему технической поддержки.

Сообщения отправляются в Telegram-группу, где под каждого пользователя создаётся отдельная чат-тема (топик).

Бот поддерживает все типы сообщений: текст, изображения, файлы, голосовые сообщения, видео, стикеры, контакты и другие медиафайлы.

---

Демонстрация

Документация: https://docs.tg-support-bot.ru/

Презентация работы бота: https://youtu.be/hIpYreHOxIk

Инструкция по установке через Docker Compose: https://youtu.be/ZAtP9qJ5q9M

Telegram-группа поддержки: https://t.me/pt_tg_support

Тестовая площадка

Для новых пользователей я сделал тестовую площадку, где можно посмотреть, как всё устроено внутри: — как выглядит проект — как работает административная панель — как происходит отправка сообщений и многое другое

🔹 Тестовая группа для сообщений: https://t.me/tg_support_bot_test

🔹 Доступ к админке: https://support.iliya-code.ru/admin/ Логин: manager@mail.ru Пароль: manager_123

🔹 Сообщество ВКонтакте: https://vk.com/club217903474

🔹 MAX: https://vk.com/club217903474

🔹 Telegram-бот: https://t.me/TgSupportTest1Bot

Буду рад вашей обратной связи! 🚀

---

Содержание

• Как это работает
• Основные возможности
• Технологический стек
• Установка и настройка
• AI помощник
• Живой чат для сайта
• API интеграция
• Мониторинг и логирование
• Поддерживаемые типы сообщений
• Интерактивные клавиатуры
• Архитектура
• Документация
• Вклад в проект
• Лицензия

---

Как это работает

┌─────────────┐         ┌─────────────┐         ┌─────────────────┐
│  Telegram   │────────▶│             │◀────────│   ВКонтакте     │
│   Users     │         │             │         │     Users       │
└─────────────┘         │             │         └─────────────────┘
                        │             │
┌─────────────┐         │   TG Bot    │         ┌─────────────────┐
│    Max      │────────▶│   Server    │◀────────│  External API   │
│   Users     │         │             │         │    Sources      │
└─────────────┘         │             │         └─────────────────┘
                        │             │
┌─────────────┐         │             │
│  Website    │────────▶│             │
│   Widget    │         │             │
└─────────────┘         └──────┬──────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │  Telegram Group      │
                    │  ┌────────────────┐  │
                    │  │ Topic: User 1  │  │
                    │  ├────────────────┤  │
                    │  │ Topic: User 2  │  │
                    │  ├────────────────┤  │
                    │  │ Topic: User 3  │  │
                    │  └────────────────┘  │
                    └──────────────────────┘

Процесс обработки сообщений

1. Получение сообщения: Пользователь отправляет сообщение боту через Telegram, ВКонтакте, виджет сайта или внешний API
2. Создание топика: Бот автоматически находит или создаёт тему (топик) в Telegram-группе для этого клиента
3. Пересылка в группу: Сообщение пересылается в соответствующую тему с информацией об отправителе
4. Ответ менеджера: Менеджеры отвечают прямо в теме — бот отслеживает их сообщения
5. Отправка клиенту: Ответ автоматически пересылается клиенту от имени бота (без раскрытия личности менеджера)

---

Основные возможности

Мультиканальность

• Telegram: Полная поддержка Telegram Bot API
• ВКонтакте: Интеграция с VK API для сообщений сообщества
• Max: Интеграция с мессенджером Max (экосистема VK/Mail.ru)
• Website Widget: Готовый виджет живого чата для встраивания на сайт
• External API: REST API для подключения сторонних источников

Коммуникация

• Все типы медиафайлов (текст, изображения, документы, голосовые, видео, стикеры, контакты)
• Автоматическая организация диалогов в топики Telegram-группы
• Приватность: клиенты не видят, кто из менеджеров им отвечает
• Настраиваемые шаблоны имен топиков

Автоматизация

• AI помощник: Интеграция с OpenAI, DeepSeek, GigaChat для генерации ответов
• Очереди сообщений с Laravel Queue
• Webhook обработка в реальном времени
• Виджет сайта на fetch-polling (без отдельного WebSocket сервера)

Админ-панель

• Рабочее место менеджера (/admin/chats): полноэкранный чат-воркспейс со списком диалогов
• Настройки (/admin/settings/*): интеграции каналов, AI-помощник, API/вебхуки, команда операторов — всё хранится в БД (таблица settings), без правки .env
• Роли: админ видит все экраны настроек; менеджер — только «Общие». Удаление чата доступно только админу
• Два режима работы менеджеров: через Telegram-супергруппу (топики) или через админ-панель

Управление и мониторинг

• Laravel Telescope: Дашборд отладки (/telescope) — запросы, исключения, логи, SQL, очереди, кэш
• Логи: Ротируемые файлы в storage/logs/, просмотр через php artisan pail или во вкладке Logs Telescope

Модерация

• Блокировка пользователей
• Закрытие обращений
• История всех сообщений
• Управление внешними источниками

---

Технологический стек

Backend:

• Laravel 12 (PHP 8.2+)
• PostgreSQL (база данных)
• Laravel Queue (обработка фоновых задач, sync)
• spatie/laravel-data (DTO)

Admin & Frontend:

• Livewire 3 + Blade (вся админка: вход /admin/login, рабочее место чата /admin/chats, настройки /admin/settings/*)
• Стандартная Laravel-аутентификация
• Tailwind CSS v4 (дизайн-система админки)
• Виджет живого чата

Интеграции:

• Telegram Bot API
• VK API
• Max Bot API (prog-time/max-php-sdk)
• AI: OpenAI / DeepSeek / GigaChat

API & документация:

• REST API + L5-Swagger (/api/documentation)

DevOps:

• Docker + Docker Compose (сервисы: pet, pgdb, nginx, laravel_queue, laravel_scheduler)
• Nginx (reverse proxy, SSL)

Мониторинг и логирование:

• Laravel Telescope (дашборд отладки: запросы, логи, SQL, очереди, исключения)
• Ротируемые лог-файлы (storage/logs/, php artisan pail)
• prog-time/tg-logger (логирование в Telegram)

Качество кода:

• PHPUnit 11 (тесты)
• PHPStan level 6 / larastan (статический анализ)
• Laravel Pint (форматирование, PSR-12 + Laravel)

---

Установка и настройка

Пошаговые инструкции по установке и настройке вынесены в документацию и Wiki:

• 📘 С чего начать: docs.tg-support-bot.ru
• 🚀 Установка через Docker Compose: инструкция
• 🖥 Установка на хостинг: инструкция

После запуска войдите в админ-панель /admin/login и настройте каналы и AI на странице Настройки (/admin/settings/*). Все токены и ключи хранятся в БД в зашифрованном виде — править .env для этого не нужно.

---

AI помощник

Бот поддерживает интеграцию с AI для автоматической генерации ответов.

Поддерживаемые провайдеры

• OpenAI (GPT-4, GPT-3.5)
• DeepSeek
• GigaChat (Сбер)

Настройка

AI настраивается полностью через админ-панель (хранится в БД, в .env ключей AI нет): учётные данные провайдера (/admin/settings/ai/{provider}, проверка ключа перед сохранением), отдельный Telegram-бот для публикации AI-ответов (/admin/settings/integrations/telegram_ai) и поведение — главный переключатель, авто-ответ (черновик на проверку менеджеру либо прямая отправка) и системный промпт (/admin/settings/ai).

Подробные пошаговые инструкции — в документации:

• 📘 Подключение AI-помощника: инструкция
• 🤖 OpenAI: инструкция
• 🤖 DeepSeek: инструкция
• 🤖 GigaChat: инструкция

Управление AI

AI работает на всех платформах пользователей (Telegram, VK, Max) и только при MANAGER_INTERFACE=telegram_group. Ответы генерируются на основе истории диалога из таблицы messages (ограничение по токенам — ai.max_context_tokens, по умолчанию 3000). Триггер — только текстовые сообщения; вложения AI не запускают.

---

Живой чат для сайта

Проект включает готовый виджет живого чата для встраивания на сайт.

Установка виджета

Виджет — это самодостаточный скрипт (public/widget/widget.js) на vanilla JS, который общается с бэкендом через REST-эндпоинты с fetch-polling (отдельный Node.js/WebSocket сервер больше не нужен).

Краткая инструкция:

1. Создайте источник и публичный ключ виджета в админ-панели на странице API/вебхуков: /admin/settings/api-webhooks/{source}
2. Вставьте перед закрывающим тегом </body> на вашем сайте один тег <script>:

<script
  src="https://yourdomain.com/widget/widget.js"
  data-domain="https://yourdomain.com"
  data-key="pub_xxxxxxxx"
  data-greeting="Напишите нам, мы онлайн!"
  data-manager="Поддержка"
  defer
></script>

3. Виджет аутентифицируется заголовком X-Widget-Key и отправляет сообщения через /api/widget/{external_id}/messages; все сообщения поступают в Telegram-группу.

📘 Подробнее — в документации: Виджет живого чата

---

API интеграция

REST API для сторонних источников

Бот предоставляет REST API для подключения внешних систем. Запросы аутентифицируются bearer-токеном из таблицы external_source_access_tokens (управление — /admin/settings/api-webhooks); неактивные токены и IP вне allowlist отклоняются middleware ApiQuery.

Основные эндпоинты ({external_id} — ID пользователя в вашей системе):

Метод	Путь	Описание
GET	/api/external/{external_id}/messages	Список сообщений
GET	/api/external/{external_id}/messages/{id_message}	Одно сообщение
POST	/api/external/{external_id}/messages	Отправить сообщение
PUT	/api/external/{external_id}/messages	Редактировать сообщение
DELETE	/api/external/{external_id}/messages	Удалить сообщение
POST	/api/external/{external_id}/files	Загрузить файл

Пример запроса:

curl -X POST https://yourdomain.com/api/external/user_12345/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "crm-system",
    "external_id": "user_12345",
    "text": "Здравствуйте, у меня вопрос по заказу"
  }'

Параметры:

• source — идентификатор внешнего источника (обязательный)
• external_id — ID пользователя в вашей системе (обязательный)
• text — текст сообщения
• attachment — массив вложений (опционально)

Когда команда отвечает внешнему пользователю, на external_sources.webhook_url отправляется webhook.

Подробная документация API доступна через Swagger: https://yourdomain.com/api/documentation

---

Мониторинг и логирование

Laravel Telescope

URL: https://yourdomain.com/telescope

Доступ защищён сессионной авторизацией админки: middleware-стек ['web', 'auth', App\Http\Middleware\TelescopeAccess::class] — гость перенаправляется на /admin/login (302), не-админ получает 403, админ открывает дашборд. HTTP Basic auth не используется (его 401-челлендж вырезается edge-прокси перед доменом). Не зависит от APP_DEBUG; чтобы выключить дашборд полностью — TELESCOPE_ENABLED=false.

Дашборд отладки: запросы, исключения, логи (Log::channel('app')), SQL-запросы, очереди/джобы, кэш, события. Записи хранятся в таблицах telescope_entries (PostgreSQL) и обрезаются ежедневно (telescope:prune --hours=48). В окружении local пишется всё; в остальных — только сбои/исключения/расписание.

Логи

Логи приложения пишутся в ротируемые файлы storage/logs/ (laravel-*.log — общий стек, app-*.log — события через Log::channel('app')). Просмотр в реальном времени:

docker exec -it pet php artisan pail
# или
tail -f storage/logs/laravel-$(date +%F).log

---

Поддерживаемые типы сообщений

Telegram

• ✅ Текстовые сообщения
• ✅ Фото
• ✅ Документы
• ✅ Голосовые сообщения
• ✅ Видео
• ✅ Видео-кружки (video notes)
• ✅ Стикеры
• ✅ Аудио
• ✅ Контакты
• ✅ Локации
• ✅ Опросы (polls)

ВКонтакте

• ✅ Текстовые сообщения
• ✅ Фото
• ✅ Документы
• ✅ Голосовые сообщения
• ✅ Видео
• ✅ Стикеры
• ✅ Аудио

Website Widget

• ✅ Текстовые сообщения
• ✅ Файлы (изображения, документы)

Max

• ✅ Текстовые сообщения
• ✅ Фото
• ✅ Документы / файлы
• ✅ Голосовые сообщения (аудио)
• ✅ Видео (пересылается как документ)
• ✅ Контакты (пересылаются как текст с именем и телефоном)
• ✅ Геопозиция (пересылается как текст с координатами и ссылкой на Google Maps)

External API

• ✅ Все типы через API (определяется параметром message_type)

---

Интерактивные клавиатуры

Бот поддерживает отправку интерактивных клавиатур пользователям через специальный синтаксис в тексте сообщения.

Синтаксис

Кнопки добавляются в текст сообщения с помощью двойных квадратных скобок:

[[Текст кнопки|тип:значение]]

Типы кнопок

Тип	Синтаксис	Описание
URL	[[Открыть сайт|url:https://example.com]]	Кнопка со ссылкой
Callback	[[Назад|callback:back]]	Inline callback кнопка
Phone	[[Отправить номер|phone]]	Запрос контакта пользователя
Text	[[Вариант 1]]	Текстовая кнопка (reply keyboard)

Примеры использования

Inline клавиатура с URL и callback кнопками:

Добрый день! Чем могу помочь?
[[Открыть сайт|url:https://example.com]]
[[Вернуться назад|callback:back]]
[[Позвать оператора|callback:operator]]

Кнопки в одном ряду (без переноса строки между ними):

Выберите вариант:
[[Да|callback:yes]] [[Нет|callback:no]]

Reply клавиатура с запросом контакта:

Для продолжения поделитесь своим номером телефона
[[Отправить номер|phone]]

Текстовые кнопки:

Выберите категорию:
[[Техническая поддержка]]
[[Вопрос по оплате]]
[[Другое]]

Поддержка по платформам

Платформа	Inline Keyboard	Reply Keyboard
Telegram	✅	✅
ВКонтакте	✅	✅
External API	✅ (через webhook)	✅ (через webhook)

Примечания

• Кнопки автоматически удаляются из текста сообщения
• Inline кнопки (url, callback) имеют приоритет над reply keyboard
• Максимум 8 кнопок в одном ряду для Telegram
• Для VK кнопки конвертируются в соответствующий формат VK API

---

Документация

Документация: https://docs.tg-support-bot.ru/

API Documentation: https://yourdomain.com/api/documentation (Swagger)

Telegram группа поддержки: https://t.me/pt_tg_support

GitHub Issues: https://github.com/prog-time/tg-support-bot/issues

---

Вклад в проект

Мы приветствуем вклад сообщества!

Пожалуйста, ознакомьтесь с CONTRIBUTING.md перед началом работы.

Как помочь проекту:

• Сообщайте об ошибках через GitHub Issues
• Предлагайте новые функции
• Улучшайте документацию
• Создавайте Pull Request'ы

---

Поддержка проекта

Если проект был вам полезен, поддержите его:

• ⭐ Поставьте звезду на GitHub
• 📢 Расскажите о проекте друзьям и коллегам
• 🤝 Внесите вклад в разработку

---

Лицензия

Проект распространяется под лицензией MIT.

Подробнее: LICENSE

---

Контакты

GitHub: https://github.com/prog-time

Проект: https://github.com/prog-time/tg-support-bot

Telegram: https://t.me/pt_tg_support

---

Сделано с ❤️ для сообщества