Security News
npm Updates Search Experience with New Objective Sorting Options
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
Modern Telegram Bot API framework for Node.js
Notice: @MKRhere has taken over as the new maintainer of Telegraf. Feel free to reach out via the Telegram group.
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.
http/https/fastify/Connect.js/express.js
compatible webhooksconst { Telegraf } = require('telegraf')
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('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'))
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 examples
folder.
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:AbCdfGhIJKlmNoQQRsTUVwxyZ
.
$ npm install telegraf
or
$ yarn add telegraf
or
$ pnpm add telegraf
Telegraf
classTelegraf
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
classctx
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.
import { Telegraf } from 'telegraf'
const bot = new Telegraf(process.env.BOT_TOKEN)
bot.command('quit', (ctx) => {
// Explicit usage
ctx.telegram.leaveChat(ctx.message.chat.id)
// Using context shortcut
ctx.leaveChat()
})
bot.on('text', (ctx) => {
// Explicit usage
ctx.telegram.sendMessage(ctx.message.chat.id, `Hello ${ctx.state.role}`)
// Using context shortcut
ctx.reply(`Hello ${ctx.state.role}`)
})
bot.on('callback_query', (ctx) => {
// Explicit usage
ctx.telegram.answerCbQuery(ctx.callbackQuery.id)
// Using context shortcut
ctx.answerCbQuery()
})
bot.on('inline_query', (ctx) => {
const result = []
// Explicit usage
ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result)
// Using context shortcut
ctx.answerInlineQuery(result)
})
bot.launch()
// Enable graceful stop
process.once('SIGINT', () => bot.stop('SIGINT'))
process.once('SIGTERM', () => bot.stop('SIGTERM'))
const { Telegraf } = require('telegraf')
const fs = require('fs')
require('dotenv')
const bot = new Telegraf(process.env.BOT_TOKEN)
// TLS options
const tlsOptions = {
key: fs.readFileSync('server-key.pem'),
cert: fs.readFileSync('server-cert.pem'),
ca: [
// This is necessary only if the client uses a self-signed certificate.
fs.readFileSync('client-cert.pem')
]
}
// Set telegram webhook
// The second argument is necessary only if the client uses a self-signed
// certificate. Including it for a verified certificate may cause things to break.
bot.telegram.setWebhook('https://server.tld:8443/secret-path', {
certificate: { source: fs.readFileSync('server-cert.pem') }
})
// Start https webhook
bot.startWebhook('/secret-path', tlsOptions, 8443)
// Http webhook, for nginx/heroku users.
bot.startWebhook('/secret-path', null, 5000)
Use webhookCallback()
if you want to attach Telegraf to an existing http server.
require('http')
.createServer(bot.webhookCallback('/secret-path'))
.listen(3000)
require('https')
.createServer(tlsOptions, bot.webhookCallback('/secret-path'))
.listen(8443)
express
example integrationfastify
example integrationkoa
example integrationbot.handleUpdate
to write new integrationsIf 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 hopefully 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.
⚠️ Always rethrow TimeoutError
!
⚠️ 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.
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', (ctx) => {
// resend existing file by file_id
ctx.replyWithSticker('123123jkbhj6b')
// send file
ctx.replyWithVideo({ source: '/path/to/video.mp4' })
// send stream
ctx.replyWithVideo({
source: fs.createReadStream('/path/to/video.mp4')
})
// send buffer
ctx.replyWithVoice({
source: Buffer.alloc()
})
// send url via Telegram server
ctx.replyWithPhoto('https://picsum.photos/200/300/')
// pipe url content
ctx.replyWithPhoto({
url: 'https://picsum.photos/200/300/?random',
filename: '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'
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('text', (ctx) => ctx.reply('Hello World'))
bot.launch()
// Enable graceful stop
process.once('SIGINT', () => bot.stop('SIGINT'))
process.once('SIGTERM', () => bot.stop('SIGTERM'))
With this simple ability, you can:
await next()
to avoid disrupting other middleware,Composer
and Router
, await next()
for updates you don't wish to handle,session
and Scenes
, extend the context by mutating ctx
before await next()
,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.
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 = ctx.chat?.first_name?.toUpperCase()
return next()
})
// ...
FAQs
Modern Telegram Bot Framework
The npm package telegraf receives a total of 54,917 weekly downloads. As such, telegraf popularity was classified as popular.
We found that telegraf demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
Security News
A supply chain attack has been detected in versions 1.95.6 and 1.95.7 of the popular @solana/web3.js library.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.