grammY
Connect to the Telegram Bot API via grammY: implementation and configuration notes.
- TypeScript-first Bot API client with built-in long-poll/webhook helpers, middleware, error handling, and rate limiter.
- Media handling is cleaner than manual fetch + FormData; covers full Bot API methods.
- Extensible: supports custom fetch (for proxy), session middleware (optional), type-safe context.
- Single client path: Removed fetch implementation; Telegram client (send + gateway) now uses grammY uniformly, with grammY throttler enabled by default.
- Gateway: monitorTelegramProvider builds grammY Bot, integrates mention/allowlist gates; media downloaded via getFile/download; outbound uses sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument. Supports long-poll or webhook via webhookCallback.
- Proxy: Optional channels.telegram.proxy, uses undici.ProxyAgent via grammY's client.baseFetch.
- Webhook support: webhook-set.ts wraps setWebhook/deleteWebhook; webhook.ts hosts callback with health checks and graceful shutdown. Gateway enables webhook mode when channels.telegram.webhookUrl + channels.telegram.webhookSecret are configured (otherwise defaults to long-poll).
- Sessions: DMs fold into agent main session (agent:<agentId>:<mainKey>); groups use agent:<agentId>:telegram:group:<chatId>; replies deterministically return to same channel.
- Config options: channels.telegram.botToken, channels.telegram.dmPolicy, channels.telegram.groups (group allowlist + mention default), 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 DM topic chat (Bot API 9.3+). This capability is independent of channel block streaming.
- Testing: grammY mocks cover DM + group mention gates and outbound sending; more media/webhook fixtures welcome.
Open Issues
- If Bot API 429 is encountered, evaluate introducing more grammY plugins (or adjusting throttler strategy).
- Add more structured media testing (stickers, voice notes, etc.).
- Make webhook listen port configurable (currently fixed at 8787 if not configured through gateway).