Інтеграція 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. Реагувати на події в реальному часі (в перспективі).

Це відмінна база для подальших проєктів: від автоматичного відповідача до системи аналітики.

Тепер ваша черга покращити цей застосунок! 😉