Пример использования Telegram API для управления ботами

Telegram-боты — это не просто чат-боты для "Привет! Как дела?". Они могут стать мощными инструментами в вашей экосистеме приложений: уведомления, автоматизация рутинных задач и даже управление IoT-устройствами. В этой лекции мы сосредоточимся на управлении ботами через Telegram API с использованием библиотеки Telethon.

Telethon предоставляет богатый интерфейс для управления ботами. Мы научимся:

• Управлять ботами и их командами.
• Автоматизировать задачи вроде рассылки сообщений или ответа на запросы.
• Обеспечивать интеграцию ботов с внешними сервисами (например, ваш FastAPI-backend).

Но для начала, убедимся, что у вас есть зарегистрированный бот.

---

Регистрация Telegram-бота

Чтобы начать, мы должны получить токен от Telegram для авторизации нашего бота. Если вы уже делали это ранее, пропустите этот шаг с гордым видом победителя.

1. Перейдите в Telegram и найдите бота @BotFather.
2. Отправьте команду /newbot и следуйте инструкциям.
3. Получите токен для вашего бота — он выглядит как строка вроде 123456789:ABCDEF123456abcdef123456ABCDEF.

Хорошо, теперь у вас есть токен. Запишите его где-нибудь (например, в .env файл, потому что кто-то однажды случайно отправил токен на GitHub и не вернулся к этому больше никогда).

---

Использование Telethon для управления ботами

Для нашей работы создадим проект с простой структурой:

telegram_bot_project/
├── bot_manager.py
├── .env
└── requirements.txt

Файл .env будет содержать токен вашего бота:

BOT_TOKEN=123456789:ABCDEF123456abcdef123456ABCDEF

Файл requirements.txt добавит Telethon:

telethon
python-dotenv

Теперь создадим основной скрипт bot_manager.py, который будет управлять ботом.

---

Настройка бота с Telethon

Для начала подключим библиотеку и инициализируем нашего бота. Здесь важно использовать TelegramClient с параметром BOT_TOKEN.

import os
from telethon import TelegramClient
from dotenv import load_dotenv

# Загружаем токен из .env файла
load_dotenv()
BOT_TOKEN = os.getenv("BOT_TOKEN")

# Создаем клиента
bot = TelegramClient('bot_session', api_id=12345, api_hash='your_api_hash').start(bot_token=BOT_TOKEN)

async def main():
    # Проверим подключение
    me = await bot.get_me()
    print(f"Бот {me.username} готов к работе!")

# Запуск клиента
with bot:
    bot.loop.run_until_complete(main())

Это базовая структура нашего бота. При запуске python bot_manager.py вы должны увидеть сообщение вроде:

Бот my_super_bot готов к работе!

Убедитесь, что вы правильно настроили токен, api_id и api_hash. Эти параметры вы можете получить, создав приложение в Telegram API Console.

Добавление команд бота

Теперь добавим функционал команд. В Telethon события для ботов обрабатываются через @bot.on(events.NewMessage).

Например, давайте создадим бот-команду /start:

from telethon import events

@bot.on(events.NewMessage(pattern='/start'))
async def start(event):
    sender = await event.get_sender()
    await event.respond(f"Привет, {sender.first_name}! Это мой супер бот.")
    print(f"{sender.first_name} использовал /start")

Теперь после запуска бота, если вы отправите сообщение "/start", он должен ответить "Привет, [ваше имя]! Это мой супер бот."

Реализация нескольких команд

Давайте добавим больше команд. Например, /help и /ping.

@bot.on(events.NewMessage(pattern='/help'))
async def help_handler(event):
    commands = """
    Вот что я могу:
    /start - Запуск бота
    /help - Вывод этой подсказки
    /ping - Проверка работоспособности
    """
    await event.respond(commands)

@bot.on(events.NewMessage(pattern='/ping'))
async def ping_handler(event):
    await event.respond("Pong!")

Теперь бот будет отвечать на /help списком команд и на /ping лаконичным "Pong!".

Рассылка сообщений

Теперь посмотрим, как бот может отправлять массовые сообщения, например, всем участникам канала.

В этом примере предположим, что у вас есть канал, и бот должен отправлять сообщения его участникам.

from telethon.tl.functions.channels import GetParticipantsRequest
from telethon.tl.types import ChannelParticipantsSearch

async def send_broadcast(channel_id, message):
    participants = await bot(GetParticipantsRequest(
        channel=channel_id,
        filter=ChannelParticipantsSearch(''),
        offset=0,
        limit=100,
        hash=0
    ))
    for user in participants.users:
        try:
            await bot.send_message(user.id, message)
        except Exception as e:
            print(f"Не удалось отправить сообщение {user.id}: {e}")

# Использование:
# await send_broadcast('your_channel_id', "Всем привет! Это массовая рассылка.")

Обработка данных с пользователей

Ваш бот может работать с пользовательскими данными. Например, вы можете сохранять историю команд, которые использовали пользователи.

user_commands = {}

@bot.on(events.NewMessage(pattern='/start'))
async def start(event):
    sender = await event.get_sender()
    user_id = sender.id
    user_commands[user_id] = user_commands.get(user_id, []) + ["/start"]
    await event.respond(f"Привет, {sender.first_name}! Вы использовали команды: {user_commands[user_id]}")

Теперь бот будет отслеживать, какие команды использовали пользователи, и сообщать об этом.

---

Более сложные сценарии: интеграция с FastAPI

Если ваш бот должен выполнять задачи на стороне вашего backend (например, забрать данные из базы), вы можете связать его с FastAPI через HTTP-запросы.

Пример — бот обращается к FastAPI для получения списка задач:

import httpx

@bot.on(events.NewMessage(pattern='/tasks'))
async def tasks(event):
    async with httpx.AsyncClient() as client:
        response = await client.get('http://localhost:8000/api/tasks/')
        tasks = response.json()
        message = "\n".join([f"{task['id']}: {task['name']}" for task in tasks])
        await event.respond(f"Ваши задачи:\n{message}")

Это пример, как легко подключить бота к вашему API.

---

Ошибки, которых стоит избегать

• Помните, что бот должен быть асинхронным. Если вы забудете использовать async перед функцией или await перед вызовом асинхронного метода, получите множество ошибок, от RuntimeWarning до падения сессии.
• Для массовой рассылки Telegram может наложить ограничения. Будьте осторожны, не отправляйте слишком много сообщений за короткий промежуток времени.

---

Теперь ваш бот не просто чат-бот, а целая автоматизированная система, готовая выполнить любые задачи. Постарайтесь использовать полученные навыки в реальных проектах: создать чат-бота для технической поддержки, учёта или автоматизации задач. 🚀