Интеграция бота с FastAPI через Webhooks

Представьте себе, что ваш бот — это официант, а клиент (Telegram) поднимает руку, чтобы что-то спросить. В традиционном подходе (Polling) официант постоянно бегает по залу в поисках поднятых рук, что довольно неэффективно. Вебхуки (Webhooks) меняют игру. Telegram сам "стучится" к вашему серверу (боту), когда есть новое сообщение. Это как если бы официант получал уведомление в наушник каждый раз, когда клиенту нужно внимание.

Вебхуки помогают избежать избыточных запросов к Telegram API и позволяют вашему приложению мгновенно реагировать на действия пользователей. Это особенно важно для масштабируемых систем, так как вебхуки более производительны и экономичны.

---

Интеграция вебхуков в FastAPI

FastAPI отлично подходит для реализации вебхуков благодаря своей асинхронной природе и легкости интеграции. FastAPI будет обрабатывать входящие сообщения от Telegram, а python-telegram-bot обеспечит взаимодействие с Telegram API. Вместе они создадут мощный и эффективный сервис.

Настройка окружения

Для начала убедимся, что у нас есть готовое окружение. У вас уже должны быть:

1. Установленная библиотека python-telegram-bot.
2. API-токен вашего бота, созданного через BotFather.
3. Установленный FastAPI и Uvicorn:

pip install fastapi uvicorn

---

Шаг 1: Создание FastAPI-приложения

Создадим базовый сервер на FastAPI, который будет слушать вебхуки.

Создайте следующую структуру:

telegram_bot_project/
├── app.py
└── requirements.txt

В файл requirements.txt добавьте:

fastapi==0.95.0
uvicorn==0.22.0
python-telegram-bot==20.3

Далее создадим файл app.py:

from fastapi import FastAPI, Request
import logging

app = FastAPI()

# Логгер для отслеживания работы приложения
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.get("/")
async def root():
    return {"message": "FastAPI Telegram Bot Webhook"}

Запустите приложение командой:

uvicorn app:app --reload

Перейдите по адресу http://127.0.0.1:8000/ — если все настроено правильно, вы увидите {"message": "FastAPI Telegram Bot Webhook"}.

Шаг 2: Подключение вебхуков

Telegram позволяет нам установить адрес вебхука с помощью метода API setWebhook. Мы будем настраивать вебхук адресом нашей FastAPI-роуты.

Добавьте в app.py:

from telegram import Update
from telegram.ext import Application, CallbackContext

TELEGRAM_API_TOKEN = "your-telegram-api-token"  # Замените на ваш API токен

# Создаем объект приложения telegram.ext
bot_app = Application.builder().token(TELEGRAM_API_TOKEN).build()

# Эндпоинт для вебхука
@app.post("/webhook")
async def telegram_webhook(request: Request):
    """Эндпоинт для обработки сообщений от Telegram через вебхук"""
    data = await request.json()  # Читаем входящие данные
    update = Update.de_json(data, bot_app.bot)  # Парсим Update объект
    await bot_app.update_queue.put(update)  # Передаем update в очередь обработки
    return {"message": "ok"}

Теперь, когда Telegram будет отправлять обновления на адрес /webhook, FastAPI будет обрабатывать их и передавать в очередь update_queue для дальнейшей обработки.

Шаг 3: Настройка вебхуков в Telegram через код

Для установки вебхука мы используем метод set_webhook. Добавим в app.py следующий код:

@app.on_event("startup")
async def set_telegram_webhook():
    """Установка вебхука при старте приложения"""
    webhook_url = "https://your-domain.com/webhook"  # Укажите ваш домен
    await bot_app.bot.set_webhook(webhook_url)
    logger.info(f"Webhook установлен: {webhook_url}")

Теперь при запуске приложения FastAPI автоматически настроит webhook для Telegram. Не забудьте указать правильный URL для вашей машины в webhook_url.

Шаг 4: Создание обработчика сообщений

Добавим примитивный обработчик для команд /start и /help:

from telegram.ext import CommandHandler

# Обработчик команды /start
async def start(update: Update, context: CallbackContext):
    await update.message.reply_text("Привет! Я Telegram бот на FastAPI. Чем могу помочь?")

# Обработчик команды /help
async def help_command(update: Update, context: CallbackContext):
    await update.message.reply_text("Список доступных команд:\n/start - приветствие\n/help - помощь")

# Регистрируем обработчики в приложении Telegram
bot_app.add_handler(CommandHandler("start", start))
bot_app.add_handler(CommandHandler("help", help_command))

Теперь наш бот отвечает на команды /start и /help. Вы можете протестировать это, написав вашему боту в Telegram.

Шаг 5: Развёртывание на удалённом сервере

Чтобы вебхук заработал, ваше приложение должно быть доступно в интернете. Здесь есть два варианта:

1. Использование публичного сервера с настоящим доменом.
2. Локальная разработка с помощью инструмента вроде ngrok.

Для ngrok выполните:

ngrok http 8000

Скопируйте полученный публичный URL и вставьте его в webhook_url.

---

Типичные ошибки и как их избегать

1. Webhook URL недоступен: убедитесь, что ваш URL публично доступен, а домен имеет SSL-сертификат (Telegram не поддерживает небезопасные HTTP соединения).
2. Ошибки в Telegram API: проверьте логи сервера. Telegram часто возвращает полезные сообщения об ошибках.
3. Необработанные исключения: если какой-то из обработчиков сообщений выбрасывает исключение, это может привести к сбоям. Используйте try-except в асинхронных функциях.

---

Теперь у вас есть базовое понимание вебхуков и их интеграции с FastAPI для Telegram-ботов. Вы можете расширять функциональность, добавлять обработку данных, интеграцию с внешними API, и даже реализовать сложные сценарии взаимодействия. В следующей лекции мы более подробно рассмотрим асинхронную обработку сообщений — оставайтесь с нами!