grammY: The Telegram Bot Framework

Common errors

• Error: Bot token is not provided!

  cause The `Bot` constructor was called with an empty or undefined string for the bot token.
  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`.

• TypeError: Cannot read properties of undefined (reading 'on')

  cause This usually indicates that the `bot` object was not correctly initialized or is `undefined` before attempting to call methods like `on` or `command`.
  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.

• Error: EACCES: permission denied, listen '0.0.0.0:80'

  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).
  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.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection.

  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.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install grammy npm
• yarn add grammy yarn
• pnpm add grammy pnpm

Imports

• Bot
  wrong:

  const { Bot } = require('grammy');

  correct:

  import { Bot } from 'grammy';

  While CommonJS `require` works, ESM `import` is the recommended and modern approach for grammY applications, especially with TypeScript.
• Context

  import { Context } from 'grammy';

  The `Context` object is fundamental, carrying all information about an incoming update. It's often extended with custom properties for specific bot logic.
• Composer
  wrong:

  import Composer from 'grammy';

  correct:

  import { Composer } from 'grammy';

  Used for modularizing bot logic by combining multiple middleware stacks. It's a named export, not a default.
• webhookCallback
  wrong:

  import { webhookCallback } from 'grammy';

  correct:

  import { webhookCallback } from 'grammy/webhooks';

  For deploying with webhooks, `webhookCallback` is imported from the dedicated `grammy/webhooks` submodule, not directly from `grammy`.

Quickstart

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.

import { Bot } from 'grammy';

// Ensure your bot token is stored securely, e.g., in environment variables
const BOT_TOKEN = process.env.BOT_TOKEN ?? '';

if (!BOT_TOKEN) {
  console.error('Error: BOT_TOKEN environment variable is not set.');
  console.error('Please get your bot token from @BotFather on Telegram.');
  process.exit(1);
}

// Create a bot object with the token
const bot = new Bot(BOT_TOKEN);

// Register listeners to handle text messages
bot.on('message:text', async (ctx) => {
  console.log(`Received text message from ${ctx.from?.first_name}: ${ctx.message.text}`);
  await ctx.reply(`Echo: ${ctx.message.text}`);
});

// Register listener for /start command
bot.command('start', async (ctx) => {
  await ctx.reply('Hello! I am your grammY bot.');
});

// Catch all other messages
bot.on('message', async (ctx) => {
  await ctx.reply('I only understand text messages and the /start command for now!');
});

// Start the bot using long polling
bot.start();

console.log('Bot started via long polling. Send it a message!');