+0
Daily
9,208
stars
944
forks
111
watchers
559
prs
1,171
issues
46
releases
README
telegraf.js
Modern Telegram Bot API framework for Node.js
For 3.x users
- 3.x docs
- 4.0 release notes
Introduction
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.
Features
- Full Telegram Bot API 7.1 support
- Excellent TypeScript typings
- Lightweight
- AWS λ
/ Firebase
/ Glitch
/ Fly.io
/ Whatever ready
- http/https/fastify/Connect.js/express.js compatible webhooks
- Extensible
Example
js
const { Telegraf } = require('telegraf')
const { message } = require('telegraf/filters')
const bot = new Telegraf(process.env.BOT_TOKEN)
bot.start((ctx) = ctx.reply('Welcome'))
bot.help((ctx) = ctx.reply('Send me a sticker'))
bot.on(message('sticker'), (ctx) = ctx.reply('👍'))
bot.hears('hi', (ctx) = ctx.reply('Hey there'))
bot.launch()
// Enable graceful stop
process.once('SIGINT', () = bot.stop('SIGINT'))
process.once('SIGTERM', () = bot.stop('SIGTERM'))
js
const { Telegraf } = require('telegraf')
const bot = new Telegraf(process.env.BOT_TOKEN)
bot.command('oldschool', (ctx) = ctx.reply('Hello'))
bot.command('hipster', Telegraf.reply('λ'))
bot.launch()
// Enable graceful stop
process.once('SIGINT', () = bot.stop('SIGINT'))
process.once('SIGTERM', () = bot.stop('SIGTERM'))
For additional bot examples see the new docs repo.
Resources
- Getting started
- API reference
- Telegram groups (sorted by number of members):
- English
- Russian
- Uzbek
- Ethiopian
- GitHub Discussions
- Dependent repositories
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.
Installation
shellscript
$ npm install telegraf
or
shellscript
$ yarn add telegraf
or
shellscript
$ 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
js
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(ctx.message.chat.id)
// Using context shortcut
await ctx.leaveChat()
})
bot.on(message('text'Top issues
#1961Getting ETIMEDOUT while running Telegraf bot in docker container with network mode host28 comments · 2024-02-29#1914Considerable delay to enter to WizardScene after adding '@telegraf/session/mongodb'25 comments · 2023-12-19#894Type defenition of ctx.scene.state19 comments · 2020-02-08#2050Support API v8.013 comments · 2024-11-30#1981Error When launch10 comments · 2024-04-20#1967Slow code suggestions in Telegraf 4.16.X after update10 comments · 2024-03-09#1889`createWebhook` always respond 404 with Koa10 comments · 2023-10-07#1817Runnable with CloudFlare Workers and other Edge Providers?9 comments · 2023-03-19
Discussions
#2097If telegraf support for cloudflare worker0 comments · 2026-09-01#2093Using Telegraf for investment alert delivery — built open source Claude Code investment skills1 comments · 2026-05-13#2085Working with bun2 comments · 2026-02-10#2081Has this project been discontinued?2 comments · 2025-10-11#2074Bot didn't get messages in huge groups (10+k members).1 comments · 2025-05-30#2073I finally made a scalable and maintainable coding structure for the Telegraf.js project0 comments · 2025-05-23#2070sendGift0 comments · 2025-03-16#2066Localization of the bot1 comments · 2025-02-20
Latest release
v4.16.3 v4.16.3 2024-02-29Fix: bug with link_preview_options.url caused client to try sending it as media
Fix: add CommandContextExtn type to Composer::{start|help|settings} (adds ctx.command, payload, args)