Nutritious Pancake Mountain

    telegraf
    TypeScript icon, indicating that this package has built-in type declarations

    4.8.5 • Public • Published

    logo

    telegraf.js

    Modern Telegram Bot API framework for Node.js

    Bot API Version install size GitHub top language English chat

    Notice: @MKRhere has taken over as the new maintainer of Telegraf. Feel free to reach out via the Telegram group.

    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

    $ yarn add telegraf
    

    or

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

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

    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 = ctx.chat?.first_name?.toUpperCase()
      return next()
    })
    // ...

    Install

    npm i telegraf

    DownloadsWeekly Downloads

    28,121

    Version

    4.8.5

    License

    MIT

    Unpacked Size

    448 kB

    Total Files

    110

    Last publish

    Collaborators

    • dotcypress
    • mkrhere
    • wojpawlik