Telegram Mini App Bot

Ключевые технологии

• python-telegram-bot - библиотека для создания Telegram ботов
• SQLModel - ORM для работы с базой данных
• AsyncPG - асинхронный PostgreSQL драйвер
• Pydantic Settings - управление конфигурацией
• HTTPX - HTTP клиент для запросов к API
• Alembic - система миграций базы данных

Что такое Telegram Mini App

Telegram Mini App (TWA - Telegram Web App) - это веб-приложение, которое запускается внутри Telegram и имеет доступ к данным пользователя и функциям мессенджера. Mini App позволяет создавать полноценные интерактивные приложения с веб-интерфейсом, не покидая Telegram.

Архитектура нашего проекта

Наш проект состоит из трех основных компонентов:

1. Backend API - FastAPI сервер для обработки данных пользователей
2. Telegram Bot (этот репозиторий) - бот для запуска Mini App и обработки команд
3. Frontend - React приложение, которое отображается в Telegram

Настройка и запуск

Предварительные требования

1. Python 3.11+
2. PostgreSQL база данных
3. uv - менеджер пакетов Python

Создание и настройка Telegram бота

1. Найдите @BotFather в Telegram
2. Отправьте команду /newbot
3. Следуйте инструкциям для создания бота
4. Получите токен бота (BOT_TOKEN)
5. Настройте Mini App:
   • Отправьте команду /mybots
   • Выберите своего бота
   • Нажмите "Bot Settings" → "Menu Button"
   • Установите URL вашего фронтенд приложения
   • Введите название для кнопки (например, "Открыть приложение")

Настройка переменных окружения

Создайте файл .env в корне проекта:

# Telegram Bot Token (получить от @BotFather)
BOT_TOKEN=your_bot_token_here

# URL Mini App (для кнопки меню)
APP_URL=https://your-mini-app-domain.com

# URL Backend API
API_URL=http://localhost:8000

# База данных PostgreSQL (совместно с Backend API)
POSTGRES_DSN=postgresql+asyncpg://username:password@localhost:5432/tg_mini_app

Установка зависимостей

uv sync

Настройка базы данных

1. Создайте базу данных PostgreSQL:

CREATE DATABASE tg_mini_app;

2. База данных будет использоваться совместно с Backend API

Запуск бота

uv run python main.py

Реализованный функционал

Команды бота:

• /start - приветствие и информация о Mini App

Кнопки интерфейса:

• 📱 Открыть приложение - запуск Mini App интерфейса
• 🔗 Проверить связь с backend - проверка связи с Backend API

Интеграция с Backend:

• Bot Auth Token - система авторизации бота через подписанные токены
• Ping endpoint - кнопка для проверки связи с Backend API с полной авторизацией
• Health Check - диагностика состояния Backend с детальной информацией об ошибках
• Передача данных пользователя в Mini App через WebApp
• Безопасная аутентификация через Telegram WebApp API

Схема авторизации бота:

1. Бот создает JWT-подобный токен с telegram_id пользователя
2. Токен подписывается секретным ключом (BOT_TOKEN)
3. Backend проверяет подпись и находит пользователя в базе данных
4. При успешной проверке возвращает данные API

Особенности:

• Автоматическая регистрация пользователей при первом запуске
• Интеграция с Mini App интерфейсом
• Логирование всех операций
• Обработка ошибок и исключений

Структура проекта

├── main.py                    # Точка входа приложения
├── config/
│   └── settings.py           # Настройки приложения
├── bot/
│   └── handlers/
│       └── start_handler.py  # Обработчики команд бота
├── database/
│   ├── engine.py            # Настройка подключения к БД
│   └── session.py           # Сессии базы данных
├── models/
│   └── user.py              # Модели пользователей
├── repositories/
│   └── user_repository.py   # Репозиторий для работы с пользователями
├── services/
│   └── profile_service.py   # Сервис для работы с профилями
└── utils/
    └── logger.py            # Настройка логирования

Разработка

Структура конфигурации

Настройки приложения находятся в config/settings.py и используют Pydantic Settings для удобного управления переменными окружения.

Интеграция с Mini App

Бот автоматически настраивается для работы с Mini App через кнопку меню. При нажатии на кнопку пользователь перенаправляется в веб-интерфейс, где может:

• Просматривать свой профиль
• Редактировать информацию о себе
• Управлять социальными сетями
• Использовать все функции приложения через удобный веб-интерфейс