Интеграция Telethon с FastAPI для автоматизации задач

Сегодня наша цель — объединить возможности FastAPI и Telethon для создания системы, которая позволит управлять Telegram через HTTP-запросы. Мы научимся:

1. Настраивать HTTP-эндпоинты FastAPI для взаимодействия с Telethon.
2. Реализовывать сценарии автоматизации, например, отправку сообщений через API.
3. Использовать асинхронность FastAPI и Telethon для быстрой обработки задач.

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

---

Что нужно подготовить?

Перед началом убедитесь, что у вас установлены:

1. FastAPI — наш веб-фреймворк для создания API.
2. Telethon — библиотека для работы с Telegram API.
3. Uvicorn — ASGI-сервер для запуска FastAPI-приложений.

Установим зависимости, если вы их ещё не устанавливали:

pip install fastapi uvicorn telethon

Кроме того, вам понадобится:

• API ID и API Hash, которые мы получили из Telegram API Developer Tools.
• Созданный файл сессии Telethon (например, my_session.session).

---

Начало интеграции

Начнём с настройки нашего проекта. Создайте структуру файлов:

telethon_fastapi/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── telegram_client.py
└── requirements.txt

Теперь разберём каждый файл.

Файл telegram_client.py: настройка Telethon

Создадим модуль для инициализации Telethon-клиента.

from telethon import TelegramClient

# Вставьте свои данные API
API_ID = 'your_api_id'
API_HASH = 'your_api_hash'

# Название файла для хранения сессий
SESSION_NAME = 'my_session'

# Создание клиента
client = TelegramClient(SESSION_NAME, API_ID, API_HASH)

Этот клиент мы будем использовать в нашем приложении FastAPI. Он подключается к Telegram по вашему API ID и сохраняет сессию в файле my_session.session, чтобы не нужно было авторизоваться каждый раз.

Не забудьте вызвать метод start() позже, чтобы клиент начал работу.

Теперь займёмся настройкой FastAPI.

from fastapi import FastAPI, HTTPException
from app.telegram_client import client

# Создание FastAPI-приложения
app = FastAPI()

# Запуск клиента Telethon
@app.on_event("startup")
async def startup_event():
    print("Запускаем Telethon клиента...")
    await client.start()

# Остановка клиента Telethon при завершении приложения
@app.on_event("shutdown")
async def shutdown_event():
    print("Останавливаем Telethon клиента...")
    await client.disconnect()

Здесь мы добавляем события startup и shutdown, чтобы Telethon-клиент автоматически запускался вместе с FastAPI.

---

Реализация API-эндпоинтов

Теперь добавим несколько эндпоинтов для управления через Telegram.

1. Эндпоинт для отправки сообщений

   Создадим эндпоинт, чтобы отправлять сообщения в Telegram через HTTP-запрос:

   @app.post("/send-message/")
   async def send_message(chat_id: int, message: str):
       """
       Отправка сообщения в чат или пользователю.
       """
       try:
           await client.send_message(chat_id, message)
           return {"status": "success", "message": f"Message sent to {chat_id}"}
       except Exception as e:
           raise HTTPException(status_code=400, detail=f"Failed to send message: {e}")
   

   Здесь:

   • chat_id — ID чата или пользователя, куда отправляется сообщение.
   • message — текст сообщения.

   Попробуйте отправить сообщение через Postman или CURL:

   curl -X POST "http://127.0.0.1:8000/send-message/" -H "Content-Type: application/json" \
       -d '{"chat_id": 123456789, "message": "Привет из FastAPI!"}'
   

---

Эндпоинт для получения информации о чате

Теперь сделаем эндпоинт, который возвращает информацию о чате по его ID.

@app.get("/get-chat/{chat_id}")
async def get_chat(chat_id: int):
    """
    Получение информации о чате по его ID.
    """
    try:
        chat = await client.get_entity(chat_id)
        return {
            "id": chat.id,
            "name": chat.title if hasattr(chat, 'title') else chat.first_name,
            "type": type(chat).__name__,
        }
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Failed to get chat info: {e}")

Этот эндпоинт полезен, если вам нужно узнать, с кем вы работаете: это чат, канал или пользователь? Вы получите ID, имя и тип.

---

Эндпоинт для чтения последних сообщений

Добавим функцию для чтения последних N сообщений из чата.

@app.get("/get-messages/{chat_id}")
async def get_messages(chat_id: int, limit: int = 10):
    """
    Получение последних сообщений из чата.
    """
    try:
        messages = await client.get_messages(chat_id, limit=limit)
        return [
            {"id": msg.id, "text": msg.text, "date": msg.date} for msg in messages
        ]
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Failed to get messages: {e}")

Теперь вы можете читать сообщения через ваш FastAPI:

curl "http://127.0.0.1:8000/get-messages/123456789?limit=5"

---

Полный пример автоматизации задач

Теперь мы можем объединить эти эндпоинты для создания сценария автоматизации. Например, вы можете:

1. Получить список последних сообщений через /get-messages/.
2. Выбрать сообщения, на которые нужно ответить.
3. Отправить ответ через /send-message/.

---

Особенности и типичные ошибки

1. Ошибка при авторизации.
   Если вы не сохранили файл сессии или неправильно указали API ID и API Hash, Telethon выбросит ошибку. Внимательно проверьте данные.
2. Асинхронность.
   Не забывайте, что функции в Telethon асинхронные. Вызов await обязателен.
3. Ограничения Telegram.
   Telegram может временно заблокировать отправку сообщений, если обнаружит слишком много запросов за короткий период. Придётся добавить ограничения на уровне FastAPI, например, использовать Rate Limiting.

---

Что мы получили?

Мы создали связку между FastAPI и Telethon, которая позволяет управлять Telegram через HTTP. Теперь ваш сервер может:

1. Автоматически отправлять сообщения.
2. Собирать данные из чатов и каналов.
3. Реагировать на события в реальном времени (в перспективе).

Это отличная основа для дальнейших проектов: от автоматического ответчика до системы аналитики.

Теперь ваша очередь улучшить это приложение! 😉