Telegram Bot API (API ботів Telegram)(Telegram Bot API для автономних агентів)

1. Огляд концепції та системна проблема

Розробка інтерфейсів для AI-агентів стикається з високим порогом входу: створення нативних мобільних застосунків потребує тривалого рев'ю в App Store/Google Play, веб-інтерфейси вимагають розробки авторизації, пуш-сповіщень та адаптивного дизайну.

Telegram Bot API надає готову транспортну інфраструктуру та кросплатформний інтерфейс користувача з аудиторією понад 900 мільйонів людей. Бот функціонує як спеціальний обліковий запис без номера телефону, керований через RESTful HTTPS-запити або Webhook-події. Для LLM-агентів Telegram став де-факто головним каналом взаємодії завдяки нативній підтримці стрімінгу повідомлень (через редагування), передачі аудіо-нотаток, кастомних клавіатур та вбудованих веб-додатків (Telegram Mini Apps).

+---------------+        HTTPS Webhook        +-------------------+
|    Клієнт     | <=========================> | Сервери Telegram  |
| (iOS/Android) |                             | (api.telegram.org)|
+---------------+                             +---------+---------+
                                                        |
                                                        | HTTPS POST /webhook
                                                        v
                                              +-------------------+
                                              | Власний бекенд    |
                                              | (Reverse Proxy /  |
                                              |  FastAPI / grammY)|
                                              +---------+---------+
                                                        |
                                                        v
                                              +-------------------+
                                              | AI Агент / LLM    |
                                              +-------------------+

2. Архітектурна таксономія та ментальна модель

Архітектура взаємодії з Telegram Bot API ділиться за методом отримання оновлень (Updates):

1. Long Polling (getUpdates):
   • Клієнтський процес тримає відкрите HTTP-з'єднання з api.telegram.org до 30–50 секунд, чекаючи на нові події.
   • Плюси: Працює локально без білої статичної IP-адреси, домену чи SSL-сертифікатів.
   • Мінуси: Високе споживання трафіку, блокування сокетів, неможливість горизонтального автоскейлінгу декількох інстансів без дублювання обробки подій.
2. Webhooks (setWebhook):
   • Сервери Telegram миттєво відправляють POST-запит з JSON payload на публічний HTTPS-ендпоінт вашого сервера при виникненні будь-якої події.
   • Плюси: Нульова затримка, максимальна ресурсоефективність сервера, можливість використання Serverless (Cloudflare Workers, AWS Lambda).
   • Вимоги: Наявність валідного TLS/SSL-сертифіката (Let's Encrypt або самопідписаний) та захист ендпоінту через secret_token.
3. Local Bot API Server (Self-hosted Telegram Bot API):
   • Компіляція офіційного C++ сервера telegram-bot-api на власному залізі.
   • Усуває обмеження на завантаження файлів до 20 МБ (підвищує до 2 ГБ) та дозволяє відправляти файли через локальні UNIX-сокети з нульовим часом копіювання.

3. Технічний пайплайн та внутрішня механіка

Налаштування продакшен-вебхука із захисним токеном

Для гарантії того, що вхідний HTTP-запит надійшов саме від серверів Telegram, обов'язково налаштовується заголовок X-Telegram-Bot-Api-Secret-Token:

curl -F "url=https://bot.example.com/api/v1/telegram-webhook" \
     -F "max_connections=100" \
     -F "secret_token=d98f7e2a4bc108e4fae8910bc472" \
     -F "allowed_updates=[\"message\",\"callback_query\"]" \
     https://api.telegram.org/bot<BOT_TOKEN>/setWebhook

Пайплайн обробки запиту (TypeScript / grammY)

import { Bot, webhookCallback } from "grammy";
import { limit } from "@grammyjs/ratelimiter";

const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);

// 1. Вбудований рейт-лімітер для користувачів
bot.use(
  limit({
    timeFrame: 2000,
    limit: 3,
    onLimitExceeded: async (ctx) => {
      await ctx.reply("Забагато запитів. Зачекайте декілька секунд.");
    },
  })
);

// 2. Обробка текстових команд та запуск AI-пайплайну
bot.command("ask", async (ctx) => {
  const query = ctx.match;
  if (!query) return ctx.reply("Вкажіть запитання для агента.");

  // Імітація статусу друку під час генерації відповіді
  await ctx.replyWithChatAction("typing");

  const response = await callAgentOrchestrator(query, ctx.from.id);
  await ctx.reply(response, { parse_mode: "HTML" });
});

export default webhookCallback(bot, "std/http", {
  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
});

4. Практичні інженерні сценарії в продакшені

01. Голосовий асистент із транскрипцією в реальному часі

Користувач надсилає голосове повідомлення (.ogg / Opus). Бекенд бота отримує file_id, завантажує аудіофайл через Bot API, конвертує його в PCM через ffmpeg та передає у Whisper API або локальну модель. Отриманий текст передається в RAG-пайплайн, і бот повертає лаконічну структуровану відповідь або синтезований голос назад у чат.

02. Інтерактивний деплой та DevOps-контроль через Inline-клавіатури

Бот підключений до Kubernetes / Coolify кластера. Під час падіння pod або тривоги в Prometheus бот генерує алерт у приватний канал розробників з кнопками: [Rollback], [View Logs], [Scale Replicas]. Натискання викликає callback_query, який ідентифікує інженера за Telegram ID, перевіряє його права у white-list та запускає безпечний сценарій безпосередньо з телефону.

03. Telegram Mini App (TMA) для аналітичних дашбордів

Замість перевантаження чату текстовими таблицями бот відкриває Web App всередині Telegram через Webview. Фронтенд на React/Next.js отримує криптографічно підписані дані initData, які бекенд валідує за допомогою HMAC-SHA256 із токеном бота. Користувач взаємодіє з інтерактивними графіками без необхідності вводити логін і пароль.

5. Підводні камені, типові помилки та безпека

1. Компрометація BOT_TOKEN: Токен бота надає повний контроль над читанням повідомлень та керуванням чатами. Ніколи не коммітьте токени в публічні репозиторії. При витоку негайно відкличте токен через @BotFather (/revoke).
2. Спецсимволи в MarkdownV2: Формат MarkdownV2 вимагає суворого екранування 18 символів (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Якщо LLM згенерує непарний символ або крапку без слеша, Telegram поверне помилку 400 Bad Request: can't parse entities, і повідомлення не надійде користувачеві. Рекомендується використовувати HTML parse mode або надійні бібліотеки форматування.
3. Блокування Event Loop синхронною обробкою: Telegram вимагає відповіді 200 OK на вхідний вебхук протягом декількох секунд. Якщо генерація LLM займає 15 секунд, а бекенд чекає завершення перед відправкою статусу вебхука, Telegram вважатиме доставку неуспішною і повторить POST-запит, спричиняючи лавиноподібне множення однакових генерацій. Завжди підтверджуйте отримання вебхука миттєво, а обробку виносьте у фонові задачі (Background Tasks / Message Queue).