Telegram Bot API

1. Aperçu du concept et problème systémique

Le développement d'interfaces pour les agents IA se heurte à une barrière à l'entrée élevée : la création d'applications mobiles natives nécessite de longs cycles de revue sur l'App Store/Google Play, tandis que les interfaces web exigent le développement de l'authentification, des notifications push et d'un design adaptatif.

Telegram Bot API fournit une infrastructure de transport prête à l'emploi et une interface utilisateur multiplateforme touchant plus de 900 millions d'utilisateurs. Le bot fonctionne comme un compte spécial sans numéro de téléphone, piloté via des requêtes RESTful HTTPS ou des événements Webhook. Pour les agents LLM, Telegram est devenu le canal d'interaction de facto grâce à sa prise en charge native du streaming de messages (via l'édition), de la transmission de notes vocales, des claviers personnalisés et des applications web intégrées (Telegram Mini Apps).

+---------------+        Webhook HTTPS        +-------------------+
|    Client     | <=========================> | Serveurs Telegram |
| (iOS/Android) |                             | (api.telegram.org)|
+---------------+                             +---------+---------+
                                                        |
                                                        | HTTPS POST /webhook
                                                        v
                                              +-------------------+
                                              | Backend personnalisé |
                                              | (Reverse Proxy /  |
                                              |  FastAPI / grammY)|
                                              +---------+---------+
                                                        |
                                                        v
                                              +-------------------+
                                              | Agent IA / LLM    |
                                              +-------------------+

2. Taxonomie architecturale et modèle mental

L'architecture d'interaction avec Telegram Bot API se divise selon la méthode de récupération des mises à jour (Updates) :

1. Long Polling (getUpdates) :
   • Le processus client maintient une connexion HTTP ouverte vers api.telegram.org pendant 30 à 50 secondes, en attente de nouveaux événements.
   • Avantages : Fonctionne localement sans nécessiter d'adresse IP statique blanche, de domaine ou de certificats SSL.
   • Inconvénients : Consommation élevée de bande passante, blocage des sockets, impossibilité de mise à l'échelle horizontale de plusieurs instances sans duplication du traitement des événements.
2. Webhooks (setWebhook) :
   • Les serveurs Telegram envoient instantanément une requête POST avec une charge utile JSON vers un point de terminaison HTTPS public de votre serveur dès qu'un événement survient.
   • Avantages : Latence nulle, efficacité maximale des ressources serveur, possibilité d'utiliser une architecture Serverless (Cloudflare Workers, AWS Lambda).
   • Exigences : Présence d'un certificat TLS/SSL valide (Let's Encrypt ou auto-signé) et protection du point de terminaison via un secret_token.
3. Local Bot API Server (Self-hosted Telegram Bot API) :
   • Compilation du serveur officiel C++ telegram-bot-api sur votre propre infrastructure.
   • Supprime la limite de téléchargement de fichiers à 20 Mo (la porte à 2 Go) et permet l'envoi de fichiers via des sockets UNIX locaux avec un temps de copie nul.

3. Pipeline technique et mécanique interne

Configuration d'un webhook de production avec jeton de sécurité

Pour garantir que la requête HTTP entrante provient bien des serveurs Telegram, il est impératif de configurer l'en-tête 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 traitement des requêtes (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. Scénarios d'ingénierie pratiques en production

01. Assistant vocal avec transcription en temps réel

L'utilisateur envoie un message vocal (.ogg / Opus). Le backend du bot reçoit le file_id, télécharge le fichier audio via Bot API, le convertit en PCM via ffmpeg et le transmet à l'API Whisper ou à un modèle local. Le texte obtenu est injecté dans le pipeline RAG, et le bot renvoie une réponse structurée concise ou une voix synthétisée directement dans le chat.

02. Déploiement interactif et contrôle DevOps via clavier Inline

Le bot est connecté à un cluster Kubernetes / Coolify. Lors de la chute d'un pod ou d'une alerte Prometheus, le bot génère une alerte dans un canal privé dédié aux développeurs, accompagnée de boutons : [Rollback], [View Logs], [Scale Replicas]. Un clic déclenche un callback_query qui identifie l'ingénieur par son ID Telegram, vérifie ses droits dans une liste blanche (white-list) et lance un scénario sécurisé directement depuis son mobile.

03. Telegram Mini App (TMA) pour tableaux de bord analytiques

Plutôt que de surcharger le chat avec des tableaux textuels, le bot ouvre une Web App au sein de Telegram via une WebView. Le frontend React/Next.js reçoit des données initData cryptographiquement signées, que le backend valide à l'aide d'HMAC-SHA256 avec le token du bot. L'utilisateur interagit avec des graphiques dynamiques sans avoir besoin de saisir login et mot de passe.

5. Pièges courants, erreurs typiques et sécurité

1. Compromission du BOT_TOKEN : Le token du bot offre un contrôle total sur la lecture des messages et la gestion des chats. Ne commitez jamais les tokens dans des dépôts publics. En cas de fuite, révoquez immédiatement le token via @BotFather (/revoke).
2. Caractères spéciaux dans MarkdownV2 : Le format MarkdownV2 exige un échappement strict de 18 caractères (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Si le LLM génère un caractère non apparié ou un point sans barre oblique inverse, Telegram renverra une erreur 400 Bad Request: can't parse entities, et le message ne sera pas livré à l'utilisateur. Il est recommandé d'utiliser le mode de parsing HTML ou des bibliothèques de formatage robustes.
3. Blocage de l'Event Loop par un traitement synchrone : Telegram exige une réponse 200 OK au webhook entrant dans un délai de quelques secondes. Si la génération LLM prend 15 secondes et que le backend attend la fin du traitement avant d'envoyer le statut du webhook, Telegram considérera la livraison comme échouée et répétera la requête POST, provoquant un effet avalanche de générations identiques. Confirmez toujours la réception du webhook instantanément et déportez le traitement vers des tâches d'arrière-plan (Background Tasks / Message Queue).