Telegram Bot API (API Ботов Telegram)

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).