telegraf

library4.16.3jsnpmunverified

Telegraf.js is a modern, lightweight, and extensible framework for developing Telegram bots using Node.js. It provides full support for the Telegram Bot API, currently at version 7.1 (as of v4.16.0), offering a comprehensive set of tools for handling messages, commands, and various update types. The library is actively maintained, with frequent minor releases incorporating new Bot API features and bug fixes, ensuring compatibility with the latest Telegram platform capabilities. Key differentiators include excellent TypeScript typings, compatibility with serverless environments like AWS Lambda and Firebase Functions, and support for various webhook setups (HTTP/HTTPS, Fastify, Express). It aims for simplicity and extensibility, allowing developers to build complex bot logic efficiently. The current stable version is 4.16.3.

web-framework

npm install telegraf

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TELEGRAF

telegraf

web-frameworkjavascriptv4.16.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Telegraf

✓ import { Telegraf } from 'telegraf'

✗ const Telegraf = require('telegraf').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

✓ import { message } from 'telegraf/filters'

✗ import { message } from 'telegraf'

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

Markup

✓ import { Markup } from 'telegraf'

✗ import { Markup } from 'telegraf/markup'

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

Composer

✓ import { Composer } from 'telegraf'

✗ const Composer = require('telegraf').Composer

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

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'));

Debug

Known issues

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

affects: >=4.0.0

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

affects: >=4.15.1

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

affects: <4.15.3

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

affects: >=4.11.0

Errors

Common errors & fixes

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

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

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

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

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

Upgrade

Version history

4.16.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

Resources

githubhttps://github.com/telegraf/telegraf ↗

packagehttps://www.npmjs.com/package/telegraf ↗

homepagehttps://telegraf.js.org ↗