Registry / communication / node-telegram-bot-api

node-telegram-bot-api

JSON →
library0.67.0jsnpmunverified

This package, `node-telegram-bot-api`, provides a comprehensive interface for interacting with the official Telegram Bot API in Node.js environments. It currently maintains version `0.67.0`, which includes robust support for Telegram Bot API up to v8.1, demonstrating an active release cadence closely aligned with new Telegram API features and ensuring compatibility. The library supports both long polling and webhook methods for receiving updates, offering flexibility for various deployment scenarios and scalability needs. Its primary differentiator is its direct and extensive mapping to the Telegram Bot API methods, providing a low-level yet convenient way to build Telegram bots. It offers robust event-driven handling for various message types and commands, along with utilities for sending messages, media, and managing chat interactions. It is a foundational choice for developers looking for a well-maintained, feature-rich, and community-supported Telegram bot development library in Node.js.

npm install node-telegram-bot-api
INSTALL
IMPORT
SIG · NODE-TELEGRAM-BOT-
N
node-telegram-bot-api
communicationjavascriptv0.67.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TelegramBot
import TelegramBot from 'node-telegram-bot-api';
ESM import for the main bot class. While the README shows CommonJS, ESM is fully supported in recent Node.js versions.
TelegramBot
const TelegramBot = require('node-telegram-bot-api');
import TelegramBot from 'node-telegram-bot-api/dist/TelegramBot';
CommonJS require pattern, commonly used in older Node.js projects or for direct `require` syntax. Avoid importing from internal `dist` paths.
TelegramBot
import type { Message } from 'node-telegram-bot-api';
import { Message } from 'node-telegram-bot-api';
For TypeScript users, type definitions are typically installed separately via `@types/node-telegram-bot-api`. Import types using `import type` to avoid runtime overhead.

Initializes a Telegram bot with long polling for updates, then echoes any message sent to it and responds specifically to the `/echo` command, acknowledging all other messages.

import TelegramBot from 'node-telegram-bot-api'; // Replace with your Telegram bot token obtained from @BotFather const token = process.env.TELEGRAM_BOT_TOKEN ?? 'YOUR_TELEGRAM_BOT_TOKEN'; if (token === 'YOUR_TELEGRAM_BOT_TOKEN') { console.warn('WARNING: Replace YOUR_TELEGRAM_BOT_TOKEN with your actual bot token from @BotFather. You should use environment variables in production.'); } // Create a bot instance using 'polling' for updates (suitable for development) const bot = new TelegramBot(token, { polling: true }); // Matches "/echo [whatever]" and sends it back bot.onText(/\/echo (.+)/, (msg, match) => { const chatId = msg.chat.id; const resp = match[1]; // The captured "whatever" bot.sendMessage(chatId, resp); console.log(`Echoed '${resp}' to chat ${chatId}`); }); // Listen for any kind of message and acknowledge it bot.on('message', (msg) => { const chatId = msg.chat.id; bot.sendMessage(chatId, 'Received your message!'); console.log(`Received message from chat ${chatId}: ${msg.text}`); }); console.log('Bot is running and listening for messages...');
Debug
Known issues
breakingMajor version updates of `node-telegram-bot-api` (e.g., v0.50.0 to v0.60.0, or v0.60.0 to v0.67.0) often include support for new Telegram Bot API versions. While this brings new features, it can also introduce breaking changes if Telegram itself deprecates or alters existing methods or object structures. Always review the `CHANGELOG.md` when upgrading across minor or major versions.
fix
Consult the official Telegram Bot API documentation and the `node-telegram-bot-api` changelog for migration guides. Update your bot's code to align with the latest API specifications.
affects: >=0.50.0
gotchaHardcoding your Telegram bot token directly in your source code is a security risk. It can lead to unauthorized access to your bot and compromise user data if your code repository is exposed.
fix
Always use environment variables (e.g., `process.env.TELEGRAM_BOT_TOKEN`) to store and retrieve sensitive tokens. For development, you can use `.env` files with packages like `dotenv`.
affects: >=0.12
gotchaFor TypeScript projects, `node-telegram-bot-api` does not ship with its own type definitions. You must install them separately from the `@types` registry to get proper type checking and IDE autocompletion.
fix
Install the type definitions as a development dependency: `npm install --save-dev @types/node-telegram-bot-api`.
affects: >=0.12
gotchaUsing 'polling' is convenient for development and small-scale bots, but it's generally less efficient and scalable for production environments with high message volumes. It can lead to higher resource consumption and potential rate-limiting issues.
fix
For production bots, consider using webhooks instead of polling. This involves setting up an HTTPS server to receive updates directly from Telegram, which is more resource-efficient and scalable. Refer to the library's documentation on webhook setup.
affects: >=0.12
Errors
Common errors & fixes
Error: ETELEGRAM: 401 Unauthorized
The bot token provided during initialization is either incorrect, revoked, or has insufficient permissions.
fix
Verify your bot token with @BotFather on Telegram. Ensure there are no typos and that the token is active. If you recently regenerated it, update your application's configuration.
TypeError: Cannot read properties of undefined (reading 'id')
This usually occurs when attempting to access properties like `msg.chat.id` or `msg.from.id` on an `msg` object that is `undefined` or does not contain the expected structure. This can happen with unexpected update types or if the `msg` object is not correctly propagated.
fix
Add nullish coalescing or optional chaining (`msg?.chat?.id`) to safely access properties. Debug your `bot.on()` or `bot.onText()` handlers to ensure the incoming `msg` object matches the expected Telegram `Message` structure for that event.
Error: Polling error: Error: connect ECONNREFUSED
The bot failed to establish a network connection to the Telegram API servers. This can be due to internet connectivity issues, firewall restrictions, DNS problems, or temporary Telegram API server outages.
fix
Check your internet connection and network configuration. Ensure no firewalls are blocking outgoing connections to `api.telegram.org`. You can also try a simple `ping api.telegram.org` from your server. If the issue persists, Telegram's API might be temporarily unavailable.
Upgrade
Version history
0.67.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
27 hits · last 30 days
node
22
OpenAI (training)
2
Resources
node-telegram-bot-api — npm install node-telegram-bot-api · libregistry