Need help with telegraf?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

telegraf
4.5K Stars 648 Forks MIT License 1.3K Commits 35 Opened issues

Description

Modern Telegram Bot Framework for Node.js

Services available

!
?

Need anything else?

Contributors list

Bot API Version GitHub top language install size Russian chat English chat

For 3.x users

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

Example

const { 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.

Resources

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:AbCdfGhIJKlmNoQQRsTUVwxyZ
.

Installation

$ 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

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

Production

Webhooks

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', { source: '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)

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

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', (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'
  })
})

Middleware

In addition to

ctx: Context
, each middleware receives
next: () => Promise
.

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: - extract information from updates and then

await next()
to avoid disrupting other middleware, - like
Composer
and
Router
,
await next()
for updates you don't wish to handle, - like
session
and
Scenes
, extend the context by mutating
ctx
before
await next()
, - intercept API calls, - reuse other people's code, - do whatever you come up with!

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('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() }) // ...

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.