Telegram Bot API

1. Visão geral do conceito e problema sistêmico

O desenvolvimento de interfaces para agentes de IA enfrenta uma barreira de entrada elevada: a criação de aplicativos móveis nativos exige longos processos de revisão na App Store/Google Play, enquanto as interfaces web demandam o desenvolvimento de autenticação, notificações push e design responsivo.

Telegram Bot API fornece infraestrutura de transporte pronta e uma interface de usuário multiplataforma com uma audiência superior a 900 milhões de pessoas. O bot opera como uma conta especial sem número de telefone, gerenciada por meio de requisições HTTPS RESTful ou eventos Webhook. Para agentes LLM, o Telegram tornou-se o canal de interação de facto, graças ao suporte nativo ao streaming de mensagens (via edição), envio de notas de voz, teclados personalizados e mini-aplicativos web integrados (Telegram Mini Apps).

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

2. Taxonomia arquitetural e modelo mental

A arquitetura de interação com a Telegram Bot API é dividida pelo método de obtenção de atualizações (Updates):

1. Long Polling (getUpdates):
   • O processo cliente mantém uma conexão HTTP aberta com api.telegram.org por até 30–50 segundos, aguardando novos eventos.
   • Prós: Funciona localmente sem necessidade de IP estático público, domínio ou certificados SSL.
   • Contras: Alto consumo de tráfego, bloqueio de sockets e impossibilidade de autoscaling horizontal de múltiplas instâncias sem duplicação no processamento de eventos.
2. Webhooks (setWebhook):
   • Os servidores do Telegram enviam instantaneamente uma requisição POST com payload JSON para um endpoint HTTPS público do seu servidor sempre que ocorre qualquer evento.
   • Prós: Latência zero, máxima eficiência de recursos do servidor e possibilidade de uso de Serverless (Cloudflare Workers, AWS Lambda).
   • Requisitos: Presença de um certificado TLS/SSL válido (Let's Encrypt ou autoassinado) e proteção do endpoint via secret_token.
3. Local Bot API Server (Self-hosted Telegram Bot API):
   • Compilação do servidor oficial em C++ telegram-bot-api em hardware próprio.
   • Elimina a limitação de upload de arquivos de 20 MB (aumentando para 2 GB) e permite enviar arquivos através de sockets UNIX locais com tempo de cópia zero.

3. Pipeline técnico e mecânica interna

Configuração de webhook de produção com token de segurança

Para garantir que a requisição HTTP recebida provenha realmente dos servidores do Telegram, configura-se obrigatoriamente o cabeçalho 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 processamento de requisições (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. Cenários de engenharia prática em produção

01. Assistente de voz com transcrição em tempo real

O usuário envia uma mensagem de voz (.ogg / Opus). O backend do bot recebe o file_id, baixa o arquivo de áudio via Bot API, converte-o para PCM usando ffmpeg e o transmite para a Whisper API ou um modelo local. O texto obtido é enviado para o pipeline RAG, e o bot retorna uma resposta concisa e estruturada ou voz sintetizada de volta ao chat.

02. Deploy interativo e controle DevOps via Inline-keyboards

O bot está conectado a um cluster Kubernetes / Coolify. Durante a queda de um pod ou um alerta no Prometheus, o bot gera um alert no canal privado dos desenvolvedores com botões: [Rollback], [View Logs], [Scale Replicas]. A pressão nos botões dispara um callback_query, que identifica o engenheiro pelo Telegram ID, verifica suas permissões na white-list e executa um script seguro diretamente do celular.

03. Telegram Mini App (TMA) para dashboards analíticos

Em vez de sobrecarregar o chat com tabelas de texto, o bot abre uma Web App dentro do Telegram via Webview. O frontend em React/Next.js recebe dados criptograficamente assinados initData, que o backend valida utilizando HMAC-SHA256 com o token do bot. O usuário interage com gráficos dinâmicos sem a necessidade de inserir login e senha.

5. Armadilhas, erros comuns e segurança

1. Comprometimento do BOT_TOKEN: O token do bot concede controle total sobre a leitura de mensagens e gestão de chats. Nunca faça commit de tokens em repositórios públicos. Em caso de vazamento, revogue imediatamente o token através do @BotFather (/revoke).
2. Caracteres especiais em MarkdownV2: O formato MarkdownV2 exige escape rigoroso de 18 caracteres (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Se a LLM gerar um caractere não pareado ou um ponto sem barra invertida, o Telegram retornará um erro 400 Bad Request: can't parse entities, e a mensagem não será entregue ao usuário. Recomenda-se usar o modo de análise HTML ou bibliotecas de formatação robustas.
3. Bloqueio do Event Loop por processamento síncrono: O Telegram exige uma resposta 200 OK para o webhook recebido dentro de poucos segundos. Se a geração da LLM levar 15 segundos e o backend esperar a conclusão antes de enviar o status do webhook, o Telegram considerará a entrega falha e repetirá a requisição POST, causando uma multiplicação exponencial de gerações idênticas. Sempre confirme o recebimento do webhook instantaneamente e mova o processamento para tarefas em segundo plano (Background Tasks / Message Queue).