Telegram Bot API

1. Überblick über das Konzept und das Systemproblem

Die Entwicklung von Benutzeroberflächen für AI-Agenten ist mit einer hohen Einstiegshürde verbunden: Die Erstellung nativer mobiler Apps erfordert langwierige Review-Prozesse im App Store bzw. Google Play, während Web-Oberflächen die Implementierung von Authentifizierung, Push-Benachrichtigungen und responsivem Design voraussetzen.

Telegram Bot API stellt eine ausgereifte Transportinfrastruktur sowie eine plattformübergreifende Benutzeroberfläche mit einer Nutzerbasis von über 900 Millionen Menschen bereit. Ein Bot fungiert als spezielles Konto ohne Telefonnummer, das über RESTful HTTPS-Requests oder Webhook-Ereignisse gesteuert wird. Für LLM-Agenten hat sich Telegram dank der nativen Unterstützung für Message-Streaming (durch Bearbeitung), Audio-Notizen, Custom Keyboards und eingebettete Web-Apps (Telegram Mini Apps) zum De-facto-Hauptkanal für Interaktionen entwickelt.

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

2. Architektonische Taxonomie und mentales Modell

Die Architektur der Interaktion mit der Telegram Bot API unterscheidet sich nach der Methode zur Abfrage von Updates:

1. Long Polling (getUpdates):
   • Der Client-Prozess hält eine offene HTTP-Verbindung zu api.telegram.org für bis zu 30–50 Sekunden aufrecht und wartet auf neue Ereignisse.
   • Vorteile: Funktioniert lokal ohne statische öffentliche IP-Adresse, Domain oder SSL-Zertifikate.
   • Nachteile: Hoher Traffic-Verbrauch, Socket-Blockaden und die Unmöglichkeit des horizontalen Autoscalings mehrerer Instanzen ohne Duplizierung der Ereignisverarbeitung.
2. Webhooks (setWebhook):
   • Die Telegram-Server senden bei jedem auftretenden Ereignis sofort einen POST-Request mit JSON-Payload an den öffentlichen HTTPS-Endpoint Ihres Servers.
   • Vorteile: Null Latenz, maximale Ressourceneffizienz des Servers und die Möglichkeit, Serverless-Architekturen (Cloudflare Workers, AWS Lambda) zu nutzen.
   • Anforderungen: Vorhandensein eines gültigen TLS/SSL-Zertifikats (Let's Encrypt oder selbstsigniert) sowie Schutz des Endpoints durch einen secret_token.
3. Local Bot API Server (Self-hosted Telegram Bot API):
   • Kompilierung des offiziellen C++ Servers telegram-bot-api auf eigener Hardware.
   • Beseitigt die Beschränkung für Datei-Uploads von 20 MB (erhöht auf 2 GB) und ermöglicht das Senden von Dateien über lokale UNIX-Sockets mit Zero-Copy-Verfahren.

3. Technischer Pipeline und interne Mechanik

Einrichtung eines Produktions-Webhooks mit Security Token

Um sicherzustellen, dass eingehende HTTP-Requests tatsächlich von den Telegram-Servern stammen, muss zwingend der Header X-Telegram-Bot-Api-Secret-Token konfiguriert werden:

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

Request-Verarbeitungspipeline (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. Praktische Engineering-Szenarien in der Produktion

01. Voice-Assistent mit Echtzeit-Transkription

Der Benutzer sendet eine Sprachnachricht (.ogg / Opus). Das Bot-Backend empfängt die file_id, lädt die Audiodatei über die Bot API herunter, konvertiert sie mittels ffmpeg in PCM und übergibt sie an die Whisper API oder ein lokales Modell. Der resultierende Text wird in die RAG-Pipeline eingespeist, und der Bot gibt eine prägnante strukturierte Antwort oder synthetisierte Sprache zurück in den Chat.

02. Interaktives Deployment und DevOps-Kontrolle via Inline-Keyboards

Der Bot ist mit einem Kubernetes- oder Coolify-Cluster verbunden. Bei einem Pod-Ausfall oder einem Prometheus-Alert generiert der Bot eine Warnung im privaten Entwickler-Kanal mit Buttons: [Rollback], [View Logs], [Scale Replicas]. Ein Klick löst einen callback_query aus, der den Ingenieur anhand seiner Telegram-ID identifiziert, seine Berechtigungen in einer Whitelist prüft und ein sicheres Skript direkt vom Mobilgerät aus startet.

03. Telegram Mini App (TMA) für analytische Dashboards

Anstatt den Chat mit textbasierten Tabellen zu überlasten, öffnet der Bot eine Web App innerhalb von Telegram über eine WebView. Das React/Next.js-Frontend erhält kryptografisch signierte initData, die das Backend unter Verwendung von HMAC-SHA256 mit dem Bot-Token validiert. Der Benutzer interagiert mit interaktiven Grafiken, ohne Login und Passwort eingeben zu müssen.

5. Fallstricke, häufige Fehler und Sicherheit

1. Kompromittierung des BOT_TOKEN: Das Bot-Token gewährt volle Kontrolle über das Lesen von Nachrichten und die Verwaltung von Chats. Committen Sie Tokens niemals in öffentlichen Repositories. Im Falle eines Lecks widerrufen Sie das Token unverzüglich über @BotFather (/revoke).
2. Sonderzeichen in MarkdownV2: Das Format MarkdownV2 erfordert strikte Escaping-Rules für 18 Zeichen (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Wenn die LLM ein unpaariges Zeichen oder einen Punkt ohne Slash generiert, gibt Telegram einen Fehler 400 Bad Request: can't parse entities zurück, und die Nachricht erreicht den Benutzer nicht. Es wird empfohlen, den HTML Parse Mode zu verwenden oder robuste Formatierungs-Bibliotheken einzusetzen.
3. Blockierung des Event Loop durch synchrone Verarbeitung: Telegram erwartet eine Antwort mit Status 200 OK auf eingehende Webhooks innerhalb weniger Sekunden. Wenn die LLM-Generierung 15 Sekunden dauert und das Backend auf deren Abschluss wartet, bevor es den Webhook-Status bestätigt, wertet Telegram die Zustellung als fehlgeschlagen und wiederholt den POST-Request. Dies führt zu einer lawinenartigen Vervielfältigung identischer Generierungen. Bestätigen Sie den Empfang des Webhooks stets sofort und verlagern Sie die Verarbeitung in Hintergrund-Tasks (Background Tasks / Message Queue).