Why Moltbot Uses grammY: Engineering a High-Performance Telegram Assistant

Engineering a persistent AI assistant requires more than just a connection to the Bot API; it requires a scalable, middleware-driven architecture.

In the most recent core update, Moltbot fully transitioned to grammY—the world's most advanced TypeScript Bot API client. This move allowed for the deprecation of hand-rolled fetch implementations in favor of a robust, professional-grade infrastructure.

Why grammY?

Prior to this migration, Moltbot relied on a custom fetch-based implementation that required manual handling of FormData, media chunks, and error retries. Moving to grammY provided three critical engineering advantages:

TS-First Design

Built-in long-poll and webhook helpers with type-safe context for all Bot API methods.

Native Throttler

Built-in handling for Bot API 429 rate limits, ensuring smooth delivery across thousands of users.

Extensible Middleware

A unified pipeline for session management, error handling, and media processing.

Single Client Architecture

Moltbot has removed all legacy Telegram client paths. grammY is now the sole engine for both message sends and gateway monitoring. By enabling the grammY throttler by default, Moltbot intelligently queues outbound messages to comply with Telegram’s strict broadcast limits.

The Gateway Provider Engine

The monitorTelegramProvider is the heart of the integration. It does the heavy lifting:

Gating: Wires mention requirements and allowlist checks before passing messages to the AI.
Media Download: Uses getFile and download to process inbound photos, videos, and documents for vision analysis.
Unified Delivery: Delivers AI-generated replies using optimized sendMessage, sendPhoto, and sendAudio pipes.

Proxies & Webhook Support

Professional Deployment Modes

For production environments, Moltbot now supports two distinct connectivity patterns:

Webhook Mode

Enabled via webhookUrl. Includes health checks and graceful shutdown listeners on port 8787.

Proxy Support

Uses undici.ProxyAgent through grammY's baseFetch for restricted network environments.

Multi-Chat Session Isolation

Moltbot implements a deterministic session mapping strategy to ensure agent context never "leaks" between different chats:

Context	Session ID Mapping
Direct Message	agent:{agentId}:{mainKey}
Group Chat	agent:{agentId}:telegram:group:{chatId}
Forum Topic	agent:{agentId}:telegram:group:{chatId}:topic:{threadId}

Draft Streaming (Bot API 9.3+)

A standout feature of the grammY implementation is the optional Draft Streaming. By utilizing the sendMessageDraft method (available in private topic chats), Moltbot can show a live, evolving text bubble to the user while the model is still generating.

This provides a significantly lower "perceived latency" compared to standard block-based messaging.

Developer Configuration Knobs

A comprehensive set of configuration flags has been exposed to give developers full control over the grammY instance:

channels.telegram.dmPolicy

channels.telegram.groupPolicy

channels.telegram.mediaMaxMb

channels.telegram.streamMode

Future Engineering Roadmap

While the migration to grammY is complete, developments continue. The current backlog includes:

Structured Media Tests

Adding extensive test fixtures for vision-processing stickers and audio-to-voice re-encoding.

Dynamic Webhook Routing

Making the internal webhook listener port configurable beyond the current default (8787).

Final Thoughts

The decision to unify Moltbot's Telegram infrastructure under grammY was driven by a single goal: Reliability. As AI assistants move from novelties to mission-critical tools, the underlying communication layer must be indestructible.

By leveraging middleware, throttlers, and professional deployment patterns, Moltbot is now ready for the next generation of ambient agents.