Skip to main content

29. Grammy Framework for Telegram Bots

Status: Accepted Date: 2025-07-06

Context​

The Arcana application's primary user interface is a Telegram bot. Interacting with the Telegram Bot API involves handling updates, managing user sessions, parsing commands, and sending formatted messages. Building these interactions from scratch by making raw HTTP requests to the API would be complex, time-consuming, and brittle. A robust, well-maintained framework is needed to handle these common tasks efficiently.

Decision​

We will use the Grammy library as the framework for all Telegram bot interactions. Grammy is a modern, well-documented, and highly-extensible framework for building Telegram bots in TypeScript. It provides a powerful middleware system, session management, and a comprehensive set of helpers that map directly to the Telegram Bot API, which significantly simplifies development.

Consequences​

Positive:

  • Developer Productivity: Grammy handles the low-level details of the Telegram API, allowing developers to focus on the bot's business logic rather than boilerplate API communication.
  • Robust Middleware: The middleware architecture makes it easy to compose functionality, such as authentication, logging, and user session management, in a clean and reusable way.
  • Strong Typing: Grammy is written in TypeScript and provides excellent type safety for API requests and responses, reducing the risk of runtime errors.
  • Extensibility: It has a rich ecosystem of plugins for additional features like interactive menus, rate limiting, and multi-language support.

Negative:

  • Third-Party Dependency: This introduces a dependency on an external library. A breaking change in a future version of Grammy could require significant refactoring in our application.
  • Framework-Specific Patterns: Developers need to learn the "Grammy way" of doing things, including its middleware flow and context object, which adds a small learning curve.

Mitigation:

  • Dependency Pinning: Pin the version of Grammy in our package.json to prevent unexpected breaking changes from minor or patch releases. Upgrades to new major versions will be a planned and tested effort.
  • Service Abstraction: Wrap the core Grammy bot instance and its setup within a dedicated TelegramService. The rest of the application will interact with this service rather than directly with the Grammy API, which will make it easier to manage or replace the dependency in the future if needed.
  • Internal Documentation: Document our specific usage patterns, common middleware configurations, and best practices for using Grammy within the project.