Telegraf.js

Common errors

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

  cause Attempting to access `ctx.session` when a session middleware has not been configured or when session data wasn't properly persisted due to an asynchronous issue (e.g., missing `await`).
  fix Ensure you have integrated a session middleware (e.g., `telegraf-session-local` or a custom one) and added it to your bot's middleware chain (`bot.use(sessionMiddleware)`). Also, check for missing `await` keywords in async middleware functions interacting with `ctx.session`.

• TypeError: Telegraf is not a constructor

  cause Incorrectly importing Telegraf in a CommonJS environment or when mixing CJS `require` with ESM `import` syntax, leading to `Telegraf` being `undefined` or an object without the constructor.
  fix For CommonJS, use `const { Telegraf } = require('telegraf')`. For ES Modules, use `import { Telegraf } from 'telegraf'`. Ensure your `package.json` `type` field is correctly set to 'module' for ESM or omitted/set to 'commonjs' for CJS.

• Error: 401: Unauthorized

  cause The provided Telegram bot token is invalid, expired, or incorrect. This is an API-level error from Telegram.
  fix Double-check your `BOT_TOKEN` environment variable or hardcoded string. Ensure it's the exact token provided by BotFather. Generate a new token if you suspect the current one is compromised or invalid.

• TypeError: ctx.reply is not a function

  cause Accessing `ctx.reply` or similar methods outside of a valid `Context` object, or within a middleware where `ctx` might be partially typed/defined without the full `TelegrafContext` methods.
  fix Ensure the code accessing `ctx.reply` is within a middleware or handler function properly receiving a `Context` object from Telegraf. In TypeScript, verify `ctx` is typed as `Context` or a more specific `ComposerContext`.

Warnings

• breaking Telegraf v4.0.0 introduced significant breaking changes from the 3.x series, including a full rewrite with improved TypeScript support and a revised API for middleware and context handling. Code written for 3.x is not directly compatible with 4.x.
  Fix: Refer to the v4.0.0 release notes and migration guide for specific changes. Update middleware registration, context access, and error handling patterns. Full TypeScript rewrite impacts type declarations.
• gotcha Session state persistence can be tricky with asynchronous operations. If `EXPERIMENTAL_SESSION_CHECKS` environment variable is enabled, Telegraf will throw errors if session is accessed/assigned after the middleware chain is thought to have exhausted, often due to missing `await`s in async code. This can lead to session data not being saved.
  Fix: Ensure all asynchronous middleware functions correctly `await` their operations. Enable `EXPERIMENTAL_SESSION_CHECKS=1` in development to catch these bugs proactively. Always return promises from async middleware if not explicitly `await`ing them.
• gotcha Prior to v4.15.3, there were known issues with media uploads (e.g., photos, documents) and `thumbnail` processing, where `sendPhoto` and similar methods might irrecoverably error or ignore thumbnails if passed invalid paths or due to internal bugs.
  Fix: Upgrade to Telegraf v4.15.3 or newer to get fixes for media upload and thumbnail handling. Always validate file paths and ensure correct media object structures are provided to API methods.
• deprecated Old patterns for importing `message` or other filters directly from 'telegraf' are incorrect. Filters are now explicitly located in the `telegraf/filters` sub-path.
  Fix: Update imports to use `import { filterName } from 'telegraf/filters'` (ESM) or `const { filterName } = require('telegraf/filters')` (CommonJS).

Install

• npm install telegraf npm
• yarn add telegraf yarn
• pnpm add telegraf pnpm

Imports

• Telegraf
  wrong:

  const Telegraf = require('telegraf').Telegraf

  correct:

  import { Telegraf } from 'telegraf'

  While Telegraf can be destructured from require, the common pattern shown in documentation for CommonJS is `const { Telegraf } = require('telegraf')`. For ESM, use named import.
• message
  wrong:

  import { message } from 'telegraf'

  correct:

  import { message } from 'telegraf/filters'

  Filters like `message` are imported from the dedicated `telegraf/filters` sub-path, not directly from the main `telegraf` package.
• Markup
  wrong:

  import { Markup } from 'telegraf/markup'

  correct:

  import { Markup } from 'telegraf'

  Markup utilities are exported directly from the main `telegraf` package. It's often used for keyboard or inline keyboard generation.
• Composer
  wrong:

  const Composer = require('telegraf').Composer

  correct:

  import { Composer } from 'telegraf'

  Composer is used for creating nested middleware and handling different update types. It's a named export from the main package.

Quickstart

This quickstart initializes a Telegraf bot with a token from environment variables, sets up basic command handlers for /start and /help, reacts to stickers, and echoes text messages. It demonstrates event listeners and graceful shutdown.

import { Telegraf } from 'telegraf';
import { message } from 'telegraf/filters';

const botToken = process.env.BOT_TOKEN ?? ''; // Ensure BOT_TOKEN is set as an environment variable

if (!botToken) {
  console.error('BOT_TOKEN environment variable is not set. Please provide your Telegram bot token.');
  process.exit(1);
}

const bot = new Telegraf(botToken);

bot.start((ctx) => ctx.reply('Welcome! Send me a message or a sticker.'));
bot.help((ctx) => ctx.reply('I can echo your messages and react to stickers!'));
bot.on(message('sticker'), (ctx) => ctx.reply('Nice sticker! 👍'));
bot.hears('hi', (ctx) => ctx.reply('Hey there! How can I help you?'));
bot.on(message('text'), (ctx) => ctx.reply(`You said: ${ctx.message.text}`));

bot.launch();

console.log('Bot launched. Press Ctrl+C to stop.');

// Enable graceful stop
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));