https://github.com/prog-time/tg-support-bot
Open-source бот для организации технической поддержки в Telegram и VK.
https://github.com/prog-time/tg-support-bot
laravel open-source php telegram telegram-bot vk-api
Last synced: about 1 month ago
JSON representation
Open-source бот для организации технической поддержки в Telegram и VK.
- Host: GitHub
- URL: https://github.com/prog-time/tg-support-bot
- Owner: prog-time
- License: mit
- Created: 2025-04-06T14:17:06.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-02-16T17:53:42.000Z (about 2 months ago)
- Last Synced: 2026-02-17T00:41:37.307Z (about 1 month ago)
- Topics: laravel, open-source, php, telegram, telegram-bot, vk-api
- Language: PHP
- Homepage: https://tg-support-bot.ru
- Size: 1.2 MB
- Stars: 182
- Watchers: 3
- Forks: 38
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# TG Support Bot — Мультиканальная платформа технической поддержки
[](./LICENSE)
[](https://www.php.net/)
[](https://laravel.com/)
[](https://www.docker.com/)
Телеграм бот для объединения сообщений из **Telegram**, **ВКонтакте** и **сторонних API источников** в единую систему технической поддержки.
Сообщения отправляются в Telegram-группу, где под каждого пользователя создаётся отдельная **чат-тема (топик)**.
Бот поддерживает **все типы сообщений**: текст, изображения, файлы, голосовые сообщения, видео, стикеры, контакты и другие медиафайлы.
---
## Демонстрация
**Презентация работы бота:** [https://youtu.be/hIpYreHOxIk](https://youtu.be/hIpYreHOxIk)
**Инструкция по установке через Docker Compose:** [https://youtu.be/ZAtP9qJ5q9M](https://youtu.be/ZAtP9qJ5q9M)
**Telegram-группа поддержки:** [https://t.me/pt_tg_support](https://t.me/pt_tg_support)
---
## Содержание
- [Как это работает](#-как-это-работает)
- [Основные возможности](#-основные-возможности)
- [Технологический стек](#-технологический-стек)
- [Быстрый старт](#-быстрый-старт)
- [Установка и настройка](#-установка-и-настройка)
- [AI помощник](#-ai-помощник)
- [Живой чат для сайта](#-живой-чат-для-сайта)
- [API интеграция](#-api-интеграция)
- [Мониторинг и логирование](#-мониторинг-и-логирование)
- [Поддерживаемые типы сообщений](#-поддерживаемые-типы-сообщений)
- [Интерактивные клавиатуры](#-интерактивные-клавиатуры)
- [Архитектура](#-архитектура)
- [Развертывание](#-развертывание)
- [Документация](#-документация)
- [Вклад в проект](#-вклад-в-проект)
- [Лицензия](#-лицензия)
---
## Как это работает
```
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
│ Telegram │────────▶│ │◀────────│ ВКонтакте │
│ Users │ │ │ │ Users │
└─────────────┘ │ │ └─────────────────┘
│ │
┌─────────────┐ │ TG Bot │ ┌─────────────────┐
│ Website │────────▶│ Server │◀────────│ External API │
│ Widget │ │ │ │ Sources │
└─────────────┘ │ │ └─────────────────┘
└──────┬──────┘
│
▼
┌──────────────────────┐
│ 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 для сообщений сообщества
- **Website Widget**: Готовый виджет живого чата для встраивания на сайт
- **External API**: REST API для подключения сторонних источников
### Коммуникация
- Все типы медиафайлов (текст, изображения, документы, голосовые, видео, стикеры, контакты)
- Автоматическая организация диалогов в топики Telegram-группы
- Приватность: клиенты не видят, кто из менеджеров им отвечает
- Настраиваемые шаблоны имен топиков
### Автоматизация
- **AI помощник**: Интеграция с OpenAI, DeepSeek, GigaChat для автоматических ответов
- Очереди сообщений с Laravel Queue
- Webhook обработка в реальном времени
- WebSocket поддержка через Socket.io
### Управление и мониторинг
- **Grafana**: Визуализация метрик и статистики
- **Loki**: Централизованное логирование
- **PgAdmin**: Управление базой данных
- **RedisInsight**: Мониторинг Redis
- Интеграция с Sentry для отслеживания ошибок
### Модерация
- Блокировка пользователей
- Закрытие обращений
- История всех сообщений
- Управление внешними источниками
---
## Технологический стек
**Backend:**
- Laravel 12.0+ (PHP 8.2+)
- PostgreSQL (база данных)
- Redis (кэш и очереди)
- Laravel Queue (обработка фоновых задач)
**Frontend & Real-time:**
- Node.js + Socket.io (WebSocket сервер)
- JavaScript (виджет чата)
**External APIs:**
- Telegram Bot API
- VK API
- OpenAI API / DeepSeek / GigaChat (AI)
**DevOps:**
- Docker + Docker Compose
- Nginx (веб-сервер)
- Certbot (SSL сертификаты)
**Monitoring & Logging:**
- Grafana (дашборды)
- Loki (логи)
- Promtail (сбор логов)
- Sentry (error tracking)
**Development:**
- PHPUnit (тестирование)
- PHPStan (статический анализ)
- Laravel Pint (code style)
---
## Быстрый старт
### Требования
- Docker 20.10+
- Docker Compose 2.0+
- Git
---
## Установка и настройка
### Подготовка
**Создайте Telegram бота:**
1. Напишите [@BotFather](https://t.me/BotFather)
2. Отправьте `/newbot`
3. Следуйте инструкциям и получите `TELEGRAM_TOKEN`
4. Отключите Privacy Mode: `/setprivacy` → Disable
**Создайте Telegram группу:**
1. Создайте новую группу
2. Добавьте в неё созданного бота как администратора
3. Включите Topics (темы) в настройках группы
4. Получите `TELEGRAM_GROUP_ID` (можно через бота [@getidsbot](https://t.me/getidsbot))
**Для ВКонтакте (опционально):**
1. Создайте сообщество ВКонтакте
2. Настройте API: Настройки → API → Создать ключ
3. Получите `VK_TOKEN`, `VK_CONFIRM_CODE`, `VK_SECRET_CODE`
### Конфигурация .env
```env
# Основные настройки
APP_NAME="TG Support Bot"
APP_URL=https://yourdomain.com
MAIN_DOMAIN=yourdomain.com
# Telegram Bot
TELEGRAM_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
TELEGRAM_GROUP_ID="-1001234567890"
TELEGRAM_SECRET_KEY="your_random_secret_key"
# VK (опционально)
VK_TOKEN="your_vk_token"
VK_CONFIRM_CODE="12345678"
VK_SECRET_CODE="your_vk_secret"
# База данных
DB_CONNECTION=pgsql
DB_HOST=pgdb
DB_PORT=5432
DB_DATABASE=support_bot
DB_USERNAME=postgres
DB_PASSWORD=secure_password
# Redis
REDIS_HOST=redis
REDIS_PASSWORD=secure_redis_password
# Шаблон имени топика
TEMPLATE_TOPIC_NAME="{first_name} {last_name} {platform}"
```
### Выберите одну из 2 инструкций
Установка на хостинг - https://github.com/prog-time/tg-support-bot/wiki/Инструкция-по-установке-бота-на-хостинг
Установка через Docker Compose - https://github.com/prog-time/tg-support-bot/wiki/Установка-через-Docker-Compose
---
## AI помощник
Бот поддерживает интеграцию с AI для автоматической генерации ответов.
### Поддерживаемые провайдеры
- **OpenAI** (GPT-4, GPT-3.5)
- **DeepSeek**
- **GigaChat** (Сбер)
### Настройка
```env
# Включить AI
AI_ENABLED=true
AI_AUTO_REPLY=false # true для автоматических ответов
# Выбор провайдера
AI_DEFAULT_PROVIDER=openai # или deepseek, gigachat
# OpenAI
OPENAI_API_KEY=sk-proj-...
OPENAI_MODEL=gpt-4
OPENAI_MAX_TOKENS=1000
OPENAI_TEMPERATURE=0.7
# DeepSeek
DEEPSEEK_CLIENT_SECRET=sk-...
DEEPSEEK_MODEL=deepseek-chat
# GigaChat
GIGACHAT_CLIENT_SECRET=your_secret
GIGACHAT_MODEL=GigaChat-2-Max
```
### Управление AI
AI помощник активируется через команды бота или автоматически при включении `AI_AUTO_REPLY=true`.
Бот может генерировать ответы на основе истории диалога и контекста.
---
## Живой чат для сайта
Проект включает готовый виджет живого чата для встраивания на сайт.
### Демо
[Пример работы виджета](https://tg-support-bot.ru/preview/chat)
### Установка виджета
Подробная инструкция доступна в [разделе Wiki](https://github.com/prog-time/tg-support-bot/wiki/).
**Краткая инструкция:**
1. Скопируйте код виджета из `public/chat-widget.js`
2. Вставьте перед закрывающим тегом `