Інтеграція бота з FastAPI через Webhooks

Уявіть, що ваш бот — це офіціант, а клієнт (Telegram) піднімає руку, щоб щось запитати. У традиційному підході (Polling) офіціант постійно бігає по залу в пошуках піднятих рук, що доволі неефективно. Webhooks змінюють гру. Telegram сам "стукає" у ваш сервер (бота), коли є нове повідомлення. Це якби офіціант отримував сповіщення в навушник щоразу, коли клієнту потрібна увага.

Webhooks допомагають уникнути надмірних запитів до Telegram API і дозволяють вашому застосунку миттєво реагувати на дії користувачів. Це особливо важливо для масштабованих систем, бо webhooks більш продуктивні і економні.

---

Інтеграція webhooks у FastAPI

FastAPI чудово підходить для реалізації webhooks завдяки своїй асинхронній природі та простоті інтеграції. FastAPI буде обробляти вхідні повідомлення від Telegram, а python-telegram-bot забезпечить взаємодію з Telegram API. Разом вони створять потужний і ефективний сервіс.

Налаштування оточення

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

1. Встановлена бібліотека python-telegram-bot.
2. API-токен вашого бота, створеного через BotFather.
3. Встановлені FastAPI і Uvicorn:

pip install fastapi uvicorn

---

Крок 1: Створення FastAPI-застосунку

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

Створіть таку структуру:

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: Підключення webhooks

Telegram дозволяє нам встановити адресу webhook з допомогою методу API setWebhook. Ми будемо налаштовувати webhook адресою нашого 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()

# Ендпоінт для webhook
@app.post("/webhook")
async def telegram_webhook(request: Request):
    """Ендпоінт для обробки повідомлень від Telegram через webhook"""
    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: Налаштування webhook у Telegram через код

Для встановлення webhook ми використовуємо метод set_webhook. Додамо в app.py наступний код:

@app.on_event("startup")
async def set_telegram_webhook():
    """Встановлення 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: Розгортання на віддаленому сервері

Щоб webhook запрацював, ваш застосунок має бути доступний в інтернеті. Тут є два варіанти:

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

Для ngrok виконайте:

ngrok http 8000

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

---

Типові помилки і як їх уникати

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

---

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