node-telegram-bot-api — Telegram Bot API Client for Node.js

Introduction

node-telegram-bot-api is a Node.js library that provides a complete wrapper around the Telegram Bot API. It handles both polling and webhook modes for receiving updates, and exposes every Telegram Bot API method as a simple async function call, making it one of the most widely used Telegram bot libraries in the JavaScript ecosystem.

What node-telegram-bot-api Does

• Wraps every Telegram Bot API method (sendMessage, sendPhoto, editMessageText, etc.)
• Supports two update modes: long polling and webhook via Express or built-in server
• Handles inline queries, callback queries, and inline keyboard interactions
• Provides event-based message handling with regex pattern matching
• Supports file uploads, downloads, and media group operations

Architecture Overview

The library creates an HTTP client that communicates with the Telegram Bot API servers. In polling mode, it continuously calls the getUpdates endpoint to fetch new messages. In webhook mode, it starts an HTTPS server (or integrates with Express) that Telegram pushes updates to. Incoming updates are parsed and emitted as typed events (message, callback_query, inline_query) that developers attach listeners to. File operations use multipart form uploads under the hood.

Self-Hosting & Configuration

• Requires Node.js 12 or newer
• Install via npm: npm install node-telegram-bot-api
• Create a bot through Telegram's @BotFather and obtain the API token
• Choose polling mode for development or webhook mode for production
• For webhooks, you need a public HTTPS URL (use a reverse proxy like Nginx with TLS)

Key Features

• Complete coverage of the Telegram Bot API including payments, games, and stickers
• Regex-based message matching for command routing
• Built-in webhook server with optional TLS support
• Promise-based API for clean async/await usage
• Lightweight with minimal dependencies

Comparison with Similar Tools

• Telegraf — Higher-level framework with middleware, scenes, and session management; node-telegram-bot-api is more lightweight and lower-level
• grammY — Modern TypeScript-first framework with plugin ecosystem; node-telegram-bot-api has a larger install base and simpler API
• aiogram — Python async equivalent; node-telegram-bot-api serves the same role for Node.js
• python-telegram-bot — Python counterpart with a similar design philosophy

FAQ

Q: Should I use polling or webhooks? A: Polling is simpler for development and works behind NATs. Webhooks are more efficient for production since Telegram pushes updates to you instead of you requesting them.

Q: How do I handle inline keyboards and callbacks? A: Send messages with an inline_keyboard in reply_markup, then listen for the callback_query event to handle button presses.

Q: Does it support TypeScript? A: Type definitions are available via @types/node-telegram-bot-api.

Q: What license is it under? A: MIT License.

Sources

• https://github.com/yagop/node-telegram-bot-api
• https://core.telegram.org/bots/api