Приклад використання 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 може накласти обмеження. Будьте обережні, не надсилайте занадто багато повідомлень за короткий проміжок часу.

---

Тепер ваш бот не просто чат-бот, а ціла автоматизована система, готова виконати будь-які задачі. Намагайтеся використовувати набуті навички в реальних проектах: створити чат-бота для техпідтримки, обліку або автоматизації задач. 🚀