Skip to main content

100. Grammy as Telegram Bot Framework

Status: Accepted Date: 2025-07-06

Context​

We need to build a universal Telegram integration library that will be used by multiple bots across different domains. We need to choose a foundational Node.js library for interacting with the Telegram Bot API. The library should be modern, well-maintained, feature-rich, and, most importantly, have excellent TypeScript support to align with our stack.

Decision​

We will adopt grammY as the core framework for the kaido-telegram library.

grammY is a modern, TypeScript-first Telegram bot framework that provides a comprehensive and elegant solution for building bots. We are choosing it for several key reasons:

  • Excellent TypeScript Support: grammY is written in TypeScript from the ground up, offering superior type safety and autocompletion for the entire Telegram Bot API.
  • Middleware System: It has a powerful and flexible middleware system, similar to Express or Koa, which is a perfect fit for our adr://middleware-driven-design.
  • Rich Feature Set: It has built-in support for sessions, interactive keyboards, command handling, and many plugins for additional functionality.
  • High Performance: The framework is designed to be highly performant and can handle a large volume of updates.
  • Active Maintenance: It is a popular and actively maintained project with a strong community.

Consequences​

Positive:

  • Developer Productivity: The excellent type safety and modern API design lead to high developer productivity and fewer bugs.
  • Clean, Composable Code: The middleware system allows us to write clean, reusable, and composable code for handling bot logic.
  • Robust and Reliable: The framework is well-tested and handles many of the complexities of the Telegram API automatically.

Negative:

  • Adds a Dependency: Introduces a significant third-party dependency that we will rely on for all Telegram interactions.
  • Learning Curve: While well-documented, developers new to the project will need to familiarize themselves with the grammY API and its concepts.

Mitigation:

  • A Well-Chosen Dependency: grammY is a high-quality, popular, and well-maintained library. The benefits of using a mature framework far outweigh the costs of building and maintaining our own low-level client.
  • Abstraction Layer: The kaido-telegram library itself acts as an abstraction layer. Most developers in other domains will interact with our simplified TelegramBotService, not directly with the grammY API, which will minimize the learning curve for non-specialists.