grammY Integration (Telegram Bot API)

Warum grammY

  • TypeScript-first Bot API Client mit eingebauten Long-Poll- und Webhook-Helfern, Middleware, Error Handling und Rate Limiter.
  • Sauberere Media-Helfer als manuelles fetch + FormData; unterstützt alle Bot API Methoden.
  • Erweiterbar: Proxy-Support über custom fetch, Session Middleware (optional), typsicherer Context.

Was wir ausgeliefert haben

  • Single Client Path: Die fetch-basierte Implementierung wurde entfernt; grammY ist jetzt der einzige Telegram Client (send + Gateway) mit standardmäßig aktiviertem grammY Throttler.
  • Gateway: monitorTelegramProvider baut einen grammY Bot, verbindet Mention/Allowlist Gating, Media-Download über getFile/download und liefert Antworten mit sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument. Unterstützt Long-Poll oder Webhook über webhookCallback.
  • Proxy: Optionales channels.telegram.proxy nutzt undici.ProxyAgent über grammYs client.baseFetch.
  • Webhook Support: webhook-set.ts umschließt setWebhook/deleteWebhook; webhook.ts hostet den Callback mit Health-Check und graceful Shutdown. Gateway aktiviert den Webhook-Modus, wenn channels.telegram.webhookUrl + channels.telegram.webhookSecret gesetzt sind (sonst nutzt es Long-Polling).
  • Sessions: Direkte Chats werden in die Agent Main Session zusammengefasst (agent:<agentId>:<mainKey>); Gruppen nutzen agent:<agentId>:telegram:group:<chatId>; Antworten werden zurück zum selben Channel geroutet.
  • Config-Optionen: channels.telegram.botToken, channels.telegram.dmPolicy, channels.telegram.groups (Allowlist + Mention Defaults), channels.telegram.allowFrom, channels.telegram.groupAllowFrom, channels.telegram.groupPolicy, channels.telegram.mediaMaxMb, channels.telegram.linkPreview, channels.telegram.proxy, channels.telegram.webhookSecret, channels.telegram.webhookUrl.
  • Draft Streaming: Optionales channels.telegram.streamMode nutzt sendMessageDraft in privaten Topic-Chats (Bot API 9.3+). Das ist getrennt vom Channel Block Streaming.
  • Tests: grammY Mocks decken DM + Group Mention Gating und Outbound Send ab; weitere Media/Webhook Fixtures sind willkommen.

Offene Fragen

  • Optional grammY Plugins (Throttler), falls wir auf Bot API 429s stoßen.
  • Mehr strukturierte Media-Tests hinzufügen (Sticker, Voice Notes).
  • Webhook Listen Port konfigurierbar machen (aktuell fest auf 8787, außer über Gateway verdrahtet).