Telegram Bot API

1. Visión general del concepto y problema sistémico

El desarrollo de interfaces para agentes AI enfrenta un alto umbral de entrada: crear aplicaciones móviles nativas requiere una larga revisión en App Store/Google Play, mientras que las interfaces web requieren el desarrollo de autenticación, notificaciones push y diseño adaptable.

Telegram Bot API proporciona una infraestructura de transporte lista y una interfaz de usuario multiplataforma con una audiencia de más de 900 millones de personas. El bot funciona como una cuenta especial sin número de teléfono, controlada a través de solicitudes RESTful HTTPS o eventos de Webhook. Para los agentes LLM, Telegram se ha convertido en el canal principal de interacción gracias al soporte nativo para el streaming de mensajes (a través de la edición), la transmisión de notas de audio, teclados personalizados y aplicaciones web integradas (Telegram Mini Apps).

+---------------+        HTTPS Webhook        +-------------------+
|    Cliente     | <=========================> | Servidores de Telegram |
| (iOS/Android) |                             | (api.telegram.org)|
+---------------+                             +---------+---------+
                                                        |
                                                        | HTTPS POST /webhook
                                                        v
                                              +-------------------+
                                              | Backend propio     |
                                              | (Reverse Proxy /   |
                                              |  FastAPI / grammY) |
                                              +---------+---------+
                                                        |
                                                        v
                                              +-------------------+
                                              | Agente AI / LLM   |
                                              +-------------------+

2. Taxonomía arquitectónica y modelo mental

La arquitectura de interacción con Telegram Bot API se divide según el método de obtención de actualizaciones (Updates):

1. Long Polling (getUpdates):
   • El proceso del cliente mantiene una conexión HTTP abierta con api.telegram.org durante 30-50 segundos, esperando nuevos eventos.
   • Pros: Funciona localmente sin una dirección IP estática pública, dominio o certificados SSL.
   • Contras: Alto consumo de tráfico, bloqueo de sockets, imposibilidad de escalado horizontal de múltiples instancias sin duplicar el procesamiento de eventos.
2. Webhooks (setWebhook):
   • Los servidores de Telegram envían inmediatamente una solicitud POST con un payload JSON a un endpoint HTTPS público de su servidor cuando ocurre cualquier evento.
   • Pros: Cero latencia, máxima eficiencia de recursos del servidor, posibilidad de usar Serverless (Cloudflare Workers, AWS Lambda).
   • Requisitos: Tener un certificado TLS/SSL válido (Let's Encrypt o auto-firmado) y proteger el endpoint a través de secret_token.
3. Servidor Local de Bot API (Self-hosted Telegram Bot API):
   • Compilación del servidor oficial en C++ telegram-bot-api en su propio hardware.
   • Elimina las restricciones de carga de archivos de hasta 20 MB (aumenta hasta 2 GB) y permite enviar archivos a través de sockets UNIX locales con tiempo de copia cero.

3. Pipeline técnico y mecánica interna

Configuración de Webhook de producción con token de seguridad

Para garantizar que la solicitud HTTP entrante provenga de los servidores de Telegram, se debe configurar obligatoriamente el encabezado 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

Pipeline de procesamiento de solicitudes (TypeScript / grammY)

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

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

// 1. Limitador de tasa integrado para usuarios
bot.use(
  limit({
    timeFrame: 2000,
    limit: 3,
    onLimitExceeded: async (ctx) => {
      await ctx.reply("Demasiadas solicitudes. Espere unos segundos.");
    },
  })
);

// 2. Procesamiento de comandos de texto y activación del pipeline AI
bot.command("ask", async (ctx) => {
  const query = ctx.match;
  if (!query) return ctx.reply("Indique una pregunta para el agente.");

  // Simulación del estado de escritura durante la generación de respuesta
  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. Escenarios prácticos de ingeniería en producción

01. Asistente de voz con transcripción en tiempo real

El usuario envía un mensaje de voz (.ogg / Opus). El backend del bot recibe file_id, descarga el archivo de audio a través de Bot API, lo convierte a PCM mediante ffmpeg y lo envía a la API de Whisper o a un modelo local. El texto obtenido se envía al pipeline RAG, y el bot devuelve una respuesta estructurada concisa o voz sintetizada de vuelta al chat.

02. Despliegue interactivo y control de DevOps a través de teclados en línea

El bot está conectado a un clúster de Kubernetes / Coolify. Durante la caída de un pod o una alerta en Prometheus, el bot genera una alerta en un canal privado de desarrolladores con botones: [Rollback], [View Logs], [Scale Replicas]. Al hacer clic, se activa callback_query, que identifica al ingeniero por su ID de Telegram, verifica sus derechos en la lista blanca y ejecuta un escenario seguro directamente desde el teléfono.

03. Telegram Mini App (TMA) para paneles de análisis

En lugar de sobrecargar el chat con tablas de texto, el bot abre una Web App dentro de Telegram a través de Webview. El frontend en React/Next.js recibe datos initData criptográficamente firmados, que el backend valida mediante HMAC-SHA256 con el token del bot. El usuario interactúa con gráficos interactivos sin necesidad de ingresar un nombre de usuario y contraseña.

5. Errores comunes, trampas y seguridad

1. Compromiso de BOT_TOKEN: El token del bot proporciona control total sobre la lectura de mensajes y la gestión de chats. Nunca comitees tokens en repositorios públicos. En caso de filtración, revoca inmediatamente el token a través de @BotFather (/revoke).
2. Caracteres especiales en MarkdownV2: El formato MarkdownV2 requiere un escape estricto de 18 caracteres (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Si LLM genera un carácter impar o un punto sin barra invertida, Telegram devolverá un error 400 Bad Request: can't parse entities, y el mensaje no llegará al usuario. Se recomienda utilizar el modo de análisis HTML o bibliotecas de formato confiables.
3. Bloqueo del Event Loop por procesamiento sincrónico: Telegram requiere una respuesta 200 OK a la solicitud de webhook entrante dentro de unos segundos. Si la generación de LLM toma 15 segundos y el backend espera a que finalice antes de enviar el estado del webhook, Telegram considerará la entrega fallida y repetirá la solicitud POST, causando una avalancha de generaciones idénticas. Siempre confirma la recepción del webhook de inmediato y realiza el procesamiento en tareas en segundo plano (Background Tasks / Message Queue).