Skip to main content

​
grammY Integration (Telegram Bot API)

​
Why grammY

  • TS-first Bot API client with built-in long-poll + webhook helpers, middleware, error handling, rate limiter.
  • Cleaner media helpers than hand-rolling fetch + FormData; supports all Bot API methods.
  • Extensible: proxy support via custom fetch, session middleware (optional), type-safe context.

​
What we shipped

  • Single client path: fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default.
  • Gateway: monitorTelegramProvider builds a grammY Bot, wires mention/allowlist gating, media download via getFile/download, and delivers replies with sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument. Supports long-poll or webhook via webhookCallback.
  • Proxy: optional channels.telegram.proxy uses undici.ProxyAgent through grammY’s client.baseFetch.
  • Webhook support: webhook-set.ts wraps setWebhook/deleteWebhook; webhook.ts hosts the callback with health + graceful shutdown. Gateway enables webhook mode when channels.telegram.webhookUrl + channels.telegram.webhookSecret are set (otherwise it long-polls).
  • Sessions: direct chats collapse into the agent main session (agent:<agentId>:<mainKey>); groups use agent:<agentId>:telegram:group:<chatId>; replies route back to the same channel.
  • Config knobs: 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: optional channels.telegram.streamMode uses sendMessageDraft in private topic chats (Bot API 9.3+). This is separate from channel block streaming.
  • Tests: grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
Open questions
  • Optional grammY plugins (throttler) if we hit Bot API 429s.
  • Add more structured media tests (stickers, voice notes).
  • Make webhook listen port configurable (currently fixed to 8787 unless wired through the gateway).