Modern Telegram Bot Framework for Node.js
Alternatives To Telegraf
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Node Telegram Bot Api7,1501,9402835 hours ago60August 29, 202272mitJavaScript
Telegram Bot API for NodeJS
Telegraf6,72368727920 days ago211September 13, 202229mitTypeScript
Modern Telegram Bot Framework for Node.js
Aiogram3,6363545a day ago75June 21, 2022102mitPython
aiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio
Telebot3,1111056 hours ago24January 22, 202239mitGo
Telebot is a Telegram bot framework in Go.
Koishi2,877736a day ago65September 08, 202140mitTypeScript
Cross-platform chatbot framework made with love
Telegram Bot Sdk2,668250475 days ago20December 10, 20202bsd-3-clausePHP
🤖 Telegram Bot API PHP SDK. Lets you build Telegram Bots easily! Supports Laravel out of the box.
Urban Bot47553 months ago41September 19, 202236mitTypeScript
🤖 The universal chatbot library based on React. Write once, launch Telegram, Discord, Facebook, ... every messenger with chatbots
Nestjs Telegraf3482a month ago29December 01, 202236mitTypeScript
🤖 Powerful Nest module for easy and fast creation Telegram bots
10 hours ago84January 14, 2023mitPHP
The Telegram bot framework that doesn't drive you nuts.
Bots Fw216
2 days ago12apache-2.0Go
Golang framework to build multilingual bots for messengers (Telegram, FB Messenger, Skype, Line, Kik, WeChat) hosted on AppEngine, Amazon, Azure, Heroku or standalone
Alternatives To Telegraf
Select To Compare

Alternative Project Comparisons


Modern Telegram Bot API framework for Node.js

Bot API Version install size GitHub top language English chat

For 3.x users


Bots are special Telegram accounts designed to handle messages automatically. Users can interact with bots by sending them command messages in private or group chats. These accounts serve as an interface for code running somewhere on your server.

Telegraf is a library that makes it simple for you to develop your own Telegram bots using JavaScript or TypeScript.



const { Telegraf } = require('telegraf');
const { message } = require('telegraf/filters');

const bot = new Telegraf(process.env.BOT_TOKEN);
bot.start((ctx) => ctx.reply('Welcome')); => ctx.reply('Send me a sticker'));
bot.on(message('sticker'), (ctx) => ctx.reply(''));
bot.hears('hi', (ctx) => ctx.reply('Hey there'));

// Enable graceful stop
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));
const { Telegraf } = require('telegraf');

const bot = new Telegraf(process.env.BOT_TOKEN);
bot.command('oldschool', (ctx) => ctx.reply('Hello'));
bot.command('hipster', Telegraf.reply(''));

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

For additional bot examples see the new docs repo.


Getting started

Telegram token

To use the Telegram Bot API, you first have to get a bot account by chatting with BotFather.

BotFather will give you a token, something like 123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ.


$ npm install telegraf


$ yarn add telegraf


$ pnpm add telegraf

Telegraf class

Telegraf instance represents your bot. It's responsible for obtaining updates and passing them to your handlers.

Start by listening to commands and launching your bot.

Context class

ctx you can see in every example is a Context instance. Telegraf creates one for each incoming update and passes it to your middleware. It contains the update, botInfo, and telegram for making arbitrary Bot API requests, as well as shorthand methods and getters.

This is probably the class you'll be using the most.

Shorthand methods

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

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.command('quit', async (ctx) => {
  // Explicit usage
  await ctx.telegram.leaveChat(;

  // Using context shortcut
  await ctx.leaveChat();

bot.on(message('text'), async (ctx) => {
  // Explicit usage
  await ctx.telegram.sendMessage(, `Hello ${ctx.state.role}`);

  // Using context shortcut
  await ctx.reply(`Hello ${ctx.state.role}`);

bot.on('callback_query', async (ctx) => {
  // Explicit usage
  await ctx.telegram.answerCbQuery(;

  // Using context shortcut
  await ctx.answerCbQuery();

bot.on('inline_query', async (ctx) => {
  const result = [];
  // Explicit usage
  await ctx.telegram.answerInlineQuery(, result);

  // Using context shortcut
  await ctx.answerInlineQuery(result);


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



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

const bot = new Telegraf(token);

bot.on(message("text"), ctx => ctx.reply("Hello"));

// Start webhook via launch method (preferred)
  webhook: {
    // Public domain for webhook; e.g.:
    domain: webhookDomain,

    // Port to listen on; e.g.: 8080
    port: port,

    // Optional path to listen for.
    // `bot.secretPathComponent()` will be used by default
    hookPath: webhookPath,

    // Optional secret to be sent back in a header for security.
    // e.g.: `crypto.randomBytes(64).toString("hex")`
    secretToken: randomAlphaNumericString,

Use createWebhook() if you want to attach Telegraf to an existing http server.

import { createServer } from "http";

createServer(await bot.createWebhook({ domain: "" })).listen(3000);
import { createServer } from "https";

createServer(tlsOptions, await bot.createWebhook({ domain: "" })).listen(8443);

Error handling

If middleware throws an error or times out, Telegraf calls bot.handleError. If it rethrows, update source closes, and then the error is printed to console and process terminates. If it does not rethrow, the error is swallowed.

Default bot.handleError always rethrows. You can overwrite it using bot.catch if you need to.

Swallowing unknown errors might leave the process in invalid state!

In production, systemd or pm2 can restart your bot if it exits for any reason.

Advanced topics

Working with files

Supported file sources:

  • Existing file_id
  • File path
  • Url
  • Buffer
  • ReadStream

Also, you can provide an optional name of a file as filename when you send the file.

bot.on('message', async (ctx) => {
  // resend existing file by file_id
  await ctx.replyWithSticker('123123jkbhj6b');

  // send file
  await ctx.replyWithVideo(Input.fromLocalFile('/path/to/video.mp4'));

  // send stream
  await ctx.replyWithVideo(Input.fromReadableStream(fs.createReadStream('/path/to/video.mp4')));

  // send buffer
  await ctx.replyWithVoice(Input.fromBuffer(Buffer.alloc()));

  // send url via Telegram server
  await ctx.replyWithPhoto(Input.fromURL(''));

  // pipe url content
  await ctx.replyWithPhoto(Input.fromURLStream('', 'kitten.jpg'));


In addition to ctx: Context, each middleware receives next: () => Promise<void>.

As in Koa and some other middleware-based libraries, await next() will call next middleware and wait for it to finish:

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

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.use(async (ctx, next) => {
  console.time(`Processing update ${ctx.update.update_id}`);
  await next() // runs next middleware
  // runs after next middleware finishes
  console.timeEnd(`Processing update ${ctx.update.update_id}`);

bot.on(message('text'), (ctx) => ctx.reply('Hello World'));

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

With this simple ability, you can:

Usage with TypeScript

Telegraf is written in TypeScript and therefore ships with declaration files for the entire library. Moreover, it includes types for the complete Telegram API via the typegram package. While most types of Telegraf's API surface are self-explanatory, there's some notable things to keep in mind.

Extending Context

The exact shape of ctx can vary based on the installed middleware. Some custom middleware might register properties on the context object that Telegraf is not aware of. Consequently, you can change the type of ctx to fit your needs in order for you to have proper TypeScript types for your data. This is done through Generics:

import { Context, Telegraf } from 'telegraf';

// Define your own context type
interface MyContext extends Context {
  myProp?: string
  myOtherProp?: number

// Create your bot and tell it about your context type
const bot = new Telegraf<MyContext>('SECRET TOKEN');

// Register middleware and launch your bot as usual
bot.use((ctx, next) => {
  // Yay, `myProp` is now available here as `string | undefined`!
  ctx.myProp =;
  return next();
// ...
Popular Telegram Projects
Popular Bot Framework Projects
Popular Messaging Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Telegram Bot
Telegram Bot Api
Bot Framework
Bot Api