Шаблон для создания Telegram-ботов на основе GPT с поддержкой групповых чатов, буферизации сообщений, обработки медиа и системы подписок.
- ⌨️ Typing indicator — индикатор "печатает..." пока бот обрабатывает запрос
- 📦 Буферизация сообщений — если пользователь отправляет несколько сообщений подряд быстрее, чем бот успевает ответить, они накапливаются и обрабатываются одним запросом к LLM. Бот проверяет наличие новых сообщений каждые 100мс во время ожидания ответа от LLM, и если они появились — прерывает ожидание и обрабатывает все накопленные сообщения вместе
- 🖼 Обработка медиа — поддержка фото и видео
- 💬 Групповые чаты — работа в группах и супергруппах (упоминания, ответы на сообщения)
- 🔄 Исправление Markdown — корректное отображение форматирования в Telegram
- ✅ Система подписок — проверка обязательной подписки на каналы-спонсоры
- 📊 Реферальная система — отслеживание источников привлечения пользователей
- Долговременная память — сохранение истории до
MAX_STORAGEсообщений - Рабочий контекст — передача последних
MAX_CONTEXTсообщений в модель - Команда
/forget— сброс истории диалога
- Личные сообщения —
/dispatchдля отправки сообщения конкретному пользователю - Массовая рассылка —
/dispatch_allдля всех пользователей - Статистика — графики активности по часам и дням недели
- Отладочный режим — пересылка сообщений с USER ID
- Docker Compose — готовые конфигурации для dev и production
- CI/CD — автоматический деплой через GitHub Actions
- Миграции БД — система версионирования схемы базы данных
- Логирование — структурированные логи с ротацией файлов
- Тесты — покрытие критичных компонентов
- Быстрый старт → — запуск бота за 3 минуты
- Развертывание → — подробное руководство
- Буферизация сообщений → — как работает накопление сообщений
- Групповые чаты → — настройка работы в группах
- Управление контекстом → — работа с памятью бота
- Реферальная система → — отслеживание источников
- Исправление Markdown → — правильное форматирование
- База данных → — структура и схема
- Миграции → — версионирование БД
- Логирование → — настройка уровней логов
- Тестирование → — запуск тестов и написание новых
- Безопасность → — защита данных и best practices
- CI/CD → — автоматический деплой
- Best Practices → — рекомендации
- Troubleshooting → — решение проблем
Проект построен по принципам Clean Architecture с четким разделением ответственности:
┌─────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ (handlers/) │
│ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ User │ │ Admin │ │ Message │ │
│ │ Handlers │ │ Handlers │ │ Handlers │ │
│ └───────────────┘ └───────────────┘ └─────────────┘ │
└────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ BUSINESS LOGIC LAYER │
│ (services/) │
│ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ LLM Service │ │ Message │ │ Stats │ │
│ │ │ │ Buffer │ │ Service │ │
│ └───────────────┘ └───────────────┘ └─────────────┘ │
└────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ (core/database.py) │
│ SQLite + aiosqlite │
└─────────────────────────────────────────────────────────┘
telegram-gpt-template/
│
├── 🚀 main.py # Точка входа
├── 🤖 core/ # Ядро приложения
│ ├── bot_instance.py # Инициализация бота
│ ├── config.py # Конфигурация
│ ├── database.py # ORM модели и БД
│ ├── filters.py # Кастомные фильтры
│ ├── states.py # FSM состояния
│ ├── utils.py # Утилиты (typing, debug)
│ └── middlewares.py # Middleware
│
├── 🎯 handlers/ # Обработчики событий
│ ├── user_handlers.py # /start, /help, /forget
│ ├── admin_handlers.py # /dispatch, /stats
│ ├── message_handlers.py # Обработка текста/медиа
│ └── subscription_handlers.py # Проверка подписок
│
├── ⚙️ services/ # Бизнес-логика
│ ├── llm_client.py # OpenRouter API клиент
│ ├── llm_service.py # Логика работы с LLM
│ ├── message_buffer.py # Буферизация сообщений
│ ├── subscription_service.py # Проверка подписок
│ └── stats_service.py # Статистика и графики
│
├── 🗄 migrations/ # Миграции БД
│ ├── migration_manager.py # Менеджер миграций
│ └── migration_*.py # Файлы миграций
│
├── 🧪 tests/ # Тесты
├── 📚 docs/ # Документация
├── 🐳 deployment/ # Docker конфиги
├── 📦 requirements/ # Зависимости
└── 🔧 config/ # Конфиги (messages.json)
✅ Разделение ответственности — каждый модуль решает свою задачу
✅ Dependency Injection — легко тестировать и заменять компоненты
✅ Service Layer — вся бизнес-логика изолирована
✅ Async/Await — максимальная производительность
✅ Type Hints — для лучшей читаемости и поддержки IDE
- Python 3.14+ — основной язык
- aiogram 3.20 — асинхронный фреймворк для Telegram Bot API
- aiosqlite — асинхронная работа с SQLite
- aiohttp — HTTP-клиент для запросов к LLM API
- OpenRouter API — доступ к различным LLM моделям
- telegramify-markdown — конвертация Markdown для Telegram
- matplotlib — генерация графиков статистики
- Docker — контейнеризация
Пользовательские:
/start— приветствие и информация/help— список команд/forget— сброс истории диалога
Администраторские:
/dispatch— отправка сообщения пользователю/dispatch_all— массовая рассылка/stats— статистика активности
Во вкладке Issues находится список потенциальных улучшений проекта. Мы будем рады вашей помощи!
Контакт автора: t.me/nikpeg
MIT License — свободно используйте в своих проектах.