Перейти к содержанию

Telegram Bot Development Guide 🛠

Руководство по локальной разработке и отладке Telegram-бота Gifty.

🚀 Локальная разработка

Есть два способа запустить бота локально:

Вариант A: Через Docker Compose (рекомендуется для полной среды)

Если вы хотите запустить весь стек (API, БД, RabbitMQ, бот) одной командой:

docker compose up -d

Бот запустится автоматически в контейнере telegram-bot вместе с остальными сервисами.

Плюсы:

  • ✅ Полная изоляция, не нужно настраивать Python окружение
  • ✅ Все зависимости (RabbitMQ, Redis, Postgres) поднимаются автоматически
  • ✅ Соответствует продакшн-окружению

Минусы:

  • ❌ Медленная итерация (нужно пересобирать образ при изменении кода)
  • ❌ Сложнее дебажить (нет прямого доступа к debugger)

Вариант B: Нативно через Python (для быстрой разработки)

Если вы активно меняете код бота и хотите видеть изменения мгновенно:

  1. Поднимите только инфраструктуру (БД, Redis, RabbitMQ): 

    docker compose up -d postgres redis rabbitmq api

  2. Создайте тестового бота через @BotFather (чтобы не конфликтовать с продом).

  3. Настройте .env для локального запуска: 

    TELEGRAM_BOT_TOKEN=ваш_тестовый_токен
INTERNAL_API_TOKEN=токен_из_.env
RABBITMQ_URL=amqp://guest:guest@localhost:5672/
API_BASE=http://localhost:8000
TELEGRAM_WEBAPP_URL=http://localhost:5173  # Или ngrok URL для тестирования Mini App

  4. Запустите бота нативно: 

    cd services/telegram_bot
python -m app.main

Плюсы:

  • ✅ Мгновенный перезапуск при изменении кода
  • ✅ Можно использовать debugger (PyCharm, VS Code)
  • ✅ Видны все print-логи в реальном времени

Минусы:

  • ❌ Нужно вручную настраивать Python окружение
  • ❌ Может отличаться от продакшн-окружения

Конфликт поллинга

Никогда не запускайте локального бота с продовым токеном, если прод уже работает. Telegram будет слать апдейты то одному, то другому, и поведение будет непредсказуемым.

Рекомендация

  • Для первого запуска и тестирования интеграций → используйте Docker Compose.
  • Для активной разработки (добавление новых команд, FSM) → используйте нативный Python.

⚛️ Frontend (Mini App Dashboard)

В папке services/telegram_bot/dashboard находится React-приложение (Vite), которое открывается внутри Telegram Web App.

Стек: React 18, Vite, TailwindCSS (если есть), Telegram WebApp SDK.

Запуск для разработки: 

cd services/telegram_bot/dashboard
npm install
npm run dev
Приложение будет доступно по адресу http://localhost:5173. Чтобы проверить его в Telegram, вам понадобится https туннель (например, ngrok), так как Telegram WebApp требует HTTPS.

Сборка: 

npm run build

Собранные файлы (dist/) должны раздаваться FastAPI или Nginx. Бот ожидает, что статика доступна по URL, который указан в WEBAPP_URL.

Настройка ngrok для локальной разработки Mini App

Зачем нужен ngrok?

Telegram Web App работает только по HTTPS. Когда вы разрабатываете Mini App локально (localhost:5173), Telegram не может открыть его, потому что:

  1. localhost недоступен извне (только на вашей машине)
  2. Нет SSL-сертификата (требуется https://)

ngrok создает публичный HTTPS-туннель к вашему локальному серверу, решая обе проблемы.

Установка ngrok

macOS (Homebrew): 

brew install ngrok

Linux/Windows: Скачайте с ngrok.com/download и добавьте в PATH.

Использование

  1. Запустите Mini App локально: 

    cd services/telegram_bot/dashboard
npm run dev
# Vite запустится на http://localhost:5173

  2. Создайте туннель: 

    ngrok http 5173

  3. Скопируйте HTTPS URL из вывода ngrok: 

    Forwarding   https://abc123.ngrok.io -> http://localhost:5173

  4. Обновите переменную окружения в .env: 

    TELEGRAM_WEBAPP_URL=https://abc123.ngrok.io

    Бот автоматически использует эту переменную при создании кнопки Mini App: 

    # services/telegram_bot/app/main.py (уже реализовано)
KeyboardButton(
    text=t("btn_scraping", lang), 
    web_app=WebAppInfo(url=settings.telegram_webapp_url)
)

  5. Перезапустите бота и проверьте кнопку в Telegram.

Ограничения бесплатной версии ngrok

  • URL меняется при каждом перезапуске (например, abc123.ngrok.io → xyz789.ngrok.io)
  • Есть лимит на количество подключений в минуту
  • Для постоянного URL нужен платный аккаунт или альтернативы (localtunnel, serveo)

Альтернативы ngrok

  • localtunnel: npx localtunnel --port 5173
  • Cloudflare Tunnel: Бесплатный, без лимитов, но сложнее в настройке

🌍 Локализация (i18n)

Все тексты бота хранятся в файле services/telegram_bot/app/strings.py в словаре STRINGS.

Структура: 

STRINGS = {
    "ru": {
        "hello": "Привет, {name}!",
        ...
    },
    "en": {
        "hello": "Hello, {name}!",
        ...
    }
}

Как добавить новый текст: 1. Придумайте уникальный ключ (например, error_database). 2. Добавьте его в оба словаря (ru и en). 3. В коде используйте функцию-хелпер t(): 

text = t("error_database", lang, name="Ivan")

Форматирование

Используйте {variable} для подстановки значений. Aiogram по умолчанию использует Markdown или HTML (зависит от настроек), убедитесь, что спецсимволы экранированы, если вставляете пользовательский ввод.

🐛 Отладка

Логирование

Бот использует стандартный модуль logging. Уровень логирования настраивается в main.py:

logging.basicConfig(level=logging.INFO)

Для детальной отладки измените на logging.DEBUG.

Типичные проблемы

1. Бот не отвечает на команды

  • Проверьте, что токен правильный: echo $TELEGRAM_BOT_TOKEN
  • Убедитесь, что нет другого экземпляра бота с тем же токеном
  • Проверьте логи: docker compose logs telegram-bot

2. Ошибка подключения к RabbitMQ

  • Убедитесь, что RabbitMQ запущен: docker compose ps rabbitmq
  • Проверьте URL: должен быть amqp://guest:guest@localhost:5672/ для локального запуска

3. Internal API недоступен

  • Проверьте, что Core API запущен: curl http://localhost:8000/health
  • Убедитесь, что INTERNAL_API_TOKEN совпадает в .env бота и API