Node.js Telegram Bot API

📦 Install

npm i node-telegram-bot-api

✍️ Note: This package is ESM-only and requires Node.js ≥ 18. Use import (not require). TypeScript types are bundled — do not install @types/node-telegram-bot-api (it would shadow the bundled, more accurate types). Upgrading from 0.6x? See the migration notes in the changelog.

🚀 Usage

import TelegramBot from 'node-telegram-bot-api';

// replace the value below with the Telegram token you receive from @BotFather
const token = 'YOUR_TELEGRAM_BOT_TOKEN';

// Create a bot that uses 'polling' to fetch new updates
const bot = new TelegramBot(token, { polling: true });

// Matches "/echo [whatever]" - the leading ^ anchors the command to the start of
// the message, so it won't match "/echo" embedded in a URL or mid-sentence.
bot.onText(/^\/echo (.+)/, (msg, match) => {
  // 'msg' is the received Message from Telegram
  // 'match' is the result of executing the regexp above on the text content
  // of the message

  const chatId = msg.chat.id;
  const resp = match?.[1] ?? ''; // the captured "whatever"

  // send back the matched "whatever" to the chat
  bot.sendMessage(chatId, resp);
});

// Listen for any kind of message. There are different kinds of messages.
bot.on('message', (msg) => {
  const chatId = msg.chat.id;

  // send a message to the chat acknowledging receipt of their message
  bot.sendMessage(chatId, 'Received your message');
});

More runnable examples live in the examples/ directory.

🌐 Proxy / custom transport

Requests use the built-in fetch. To route a single bot instance through a proxy (without affecting the rest of the process), pass an undici dispatcher via request.fetchOptions:

import TelegramBot from 'node-telegram-bot-api';
import { ProxyAgent } from 'undici';

const bot = new TelegramBot(token, {
  polling: true,
  request: { fetchOptions: { dispatcher: new ProxyAgent('http://127.0.0.1:8080') } },
});

For full control you can supply your own fetch implementation instead via request.fetch (useful for custom proxying, instrumentation, or tests). Both are scoped to that bot instance, so different bots can use different proxies.

📚 Documentation

• Usage
• Examples
• Migration guide (0.6x → 1.0)
• Tutorials
• Help Information
• API Reference — generated from source; the package also ships its own TypeScript types, and method signatures mirror the official Bot API
• Contributing to the Project

Note: Code for the latest release resides on the master branch, and pull requests should target master.

💭 Community

We thank all the developers in the Open-Source community who continuously take their time and effort in advancing this project. See our list of contributors.

We have a Telegram channel where we post updates on the Project. Head over and subscribe!

We also have a Telegram group to discuss issues related to this library.

Some things built using this library that might interest you:

• tgfancy: A fancy, higher-level wrapper for Telegram Bot API
• node-telegram-bot-api-middleware: Middleware for node-telegram-bot-api
• teleirc: A simple Telegram ↔ IRC gateway
• bot-brother: Node.js library to help you easily create telegram bots
• redbot: A Node-RED plugin to create telegram bots visually
• node-telegram-keyboard-wrapper: A wrapper to improve keyboards structures creation through a more easy-to-see way (supports Inline Keyboards, Reply Keyboard, Remove Keyboard and Force Reply)
• beetube-bot: A telegram bot for music, videos, movies, EDM tracks, torrent downloads, files and more.
• telegram-inline-calendar: Date and time picker and inline calendar for Node.js telegram bots.
• telegram-captcha: Telegram bot to protect Telegram groups from automatic bots.
• @toptl/node-telegram-bot-api: Plugin for TOP.TL, the Telegram directory. Auto-tracks bot stats and enables vote checking.

👥 Contributors

License

The MIT License (MIT)

Copyright © 2019 Yago