{"id":10962,"library":"grammy","title":"grammY: The Telegram Bot Framework","description":"grammY is a powerful, user-friendly, and highly efficient framework designed for creating Telegram bots using TypeScript or JavaScript. As of version 1.42.0, it offers robust support for the latest Telegram Bot API features, frequently releasing updates to keep pace with Telegram's evolving platform (e.g., Bot API 9.6 in recent releases). It distinguishes itself with comprehensive documentation, seamless integration with web frameworks (like Express, Koa, Bun, Cloudflare Workers) and databases, and a thriving ecosystem of plugins. The library emphasizes scalability and performance, making it suitable for both novice bot developers and large-scale applications. It runs on Node.js (requiring ^12.20.0 || >=14.13.1) and Deno.","status":"active","version":"1.42.0","language":"javascript","source_language":"en","source_url":"https://github.com/grammyjs/grammY","tags":["javascript","telegram","bot","api","client","framework","library","grammy","typescript"],"install":[{"cmd":"npm install grammy","lang":"bash","label":"npm"},{"cmd":"yarn add grammy","lang":"bash","label":"yarn"},{"cmd":"pnpm add grammy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the recommended and modern approach for grammY applications, especially with TypeScript.","wrong":"const { Bot } = require('grammy');","symbol":"Bot","correct":"import { Bot } from 'grammy';"},{"note":"The `Context` object is fundamental, carrying all information about an incoming update. It's often extended with custom properties for specific bot logic.","symbol":"Context","correct":"import { Context } from 'grammy';"},{"note":"Used for modularizing bot logic by combining multiple middleware stacks. It's a named export, not a default.","wrong":"import Composer from 'grammy';","symbol":"Composer","correct":"import { Composer } from 'grammy';"},{"note":"For deploying with webhooks, `webhookCallback` is imported from the dedicated `grammy/webhooks` submodule, not directly from `grammy`.","wrong":"import { webhookCallback } from 'grammy';","symbol":"webhookCallback","correct":"import { webhookCallback } from 'grammy/webhooks';"}],"quickstart":{"code":"import { Bot } from 'grammy';\n\n// Ensure your bot token is stored securely, e.g., in environment variables\nconst BOT_TOKEN = process.env.BOT_TOKEN ?? '';\n\nif (!BOT_TOKEN) {\n  console.error('Error: BOT_TOKEN environment variable is not set.');\n  console.error('Please get your bot token from @BotFather on Telegram.');\n  process.exit(1);\n}\n\n// Create a bot object with the token\nconst bot = new Bot(BOT_TOKEN);\n\n// Register listeners to handle text messages\nbot.on('message:text', async (ctx) => {\n  console.log(`Received text message from ${ctx.from?.first_name}: ${ctx.message.text}`);\n  await ctx.reply(`Echo: ${ctx.message.text}`);\n});\n\n// Register listener for /start command\nbot.command('start', async (ctx) => {\n  await ctx.reply('Hello! I am your grammY bot.');\n});\n\n// Catch all other messages\nbot.on('message', async (ctx) => {\n  await ctx.reply('I only understand text messages and the /start command for now!');\n});\n\n// Start the bot using long polling\nbot.start();\n\nconsole.log('Bot started via long polling. Send it a message!');","lang":"typescript","description":"This quickstart initializes a grammY bot, registers handlers for text messages and the `/start` command, and starts it using long polling. It demonstrates basic message echoing and includes essential error handling for the bot token, ensuring the bot runs securely by advocating environment variables for sensitive data."},"warnings":[{"fix":"Always load your bot token from environment variables (`process.env.BOT_TOKEN`) or a secure configuration management system. Never commit tokens to version control.","message":"Hardcoding your bot token directly into source code is a significant security risk. Anyone with access to your code repository could use your bot's token.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update grammY to its latest version to ensure compatibility with the Telegram Bot API. Monitor the grammY release notes for any migration guides or breaking changes, especially when new Bot API versions are released.","message":"grammY frequently updates to support the latest Telegram Bot API versions. While this keeps the library current, it means that older grammY versions might not correctly handle new Bot API features or changes, potentially leading to unexpected behavior or `400 Bad Request` errors if your bot uses unsupported API methods.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Standardize on ES Modules (`import`/`export`) for new projects and consider migrating existing CommonJS projects. Ensure your `package.json` specifies `\"type\": \"module\"` for ESM, or use a TypeScript compiler that targets ESM.","message":"While grammY supports both CommonJS (`require`) and ES Modules (`import`), the documentation and examples increasingly favor ESM. Mixing module systems within a single project can lead to `TypeError: require is not a function` or other module resolution issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that your server's firewall allows traffic on the webhook port. Ensure the URL provided to Telegram via `bot.setWebhook()` is correct and resolves to your server. Use a service like `ngrok` for local development to test webhook functionality.","message":"When deploying with webhooks, ensure your server is correctly configured to listen on the specified port and is publicly accessible. Common errors include port conflicts, firewalls blocking incoming connections, or incorrect URL configurations for Telegram to send updates.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `BOT_TOKEN` environment variable is set before running your bot, or pass a valid token string to the `Bot` constructor. Example: `process.env.BOT_TOKEN`.","cause":"The `Bot` constructor was called with an empty or undefined string for the bot token.","error":"Error: Bot token is not provided!"},{"fix":"Verify that `new Bot(BOT_TOKEN)` successfully created a bot instance and that `BOT_TOKEN` is a valid string. Check for typos or incorrect variable assignments.","cause":"This usually indicates that the `bot` object was not correctly initialized or is `undefined` before attempting to call methods like `on` or `command`.","error":"TypeError: Cannot read properties of undefined (reading 'on')"},{"fix":"Use a non-privileged port (e.g., 3000, 8080) for your webhook server if running as a non-root user. If you must use a privileged port, configure your system to allow the bot's process to bind to it, or use a reverse proxy (like Nginx) to forward requests.","cause":"Commonly occurs when trying to run a webhook server on a privileged port (like 80 or 443) without sufficient user permissions (e.g., running as a non-root user).","error":"Error: EACCES: permission denied, listen '0.0.0.0:80'"},{"fix":"Always use `await` for asynchronous operations (e.g., `ctx.reply()`, API calls) inside your middleware. Implement proper error handling using `try...catch` blocks or `bot.catch()` middleware to gracefully manage errors.","cause":"Asynchronous middleware functions or API calls within your bot's handlers are not properly `await`ed or do not have `.catch()` blocks, leading to unhandled errors.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection."}],"ecosystem":"npm"}