{"id":13669,"library":"node-telegram-bot-api","title":"Node.js Telegram Bot API Client","description":"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.","status":"active","version":"0.67.0","language":"javascript","source_language":"en","source_url":"https://github.com/yagop/node-telegram-bot-api","tags":["javascript","telegram","telegram bot","telegram bot api","bot"],"install":[{"cmd":"npm install node-telegram-bot-api","lang":"bash","label":"npm"},{"cmd":"yarn add node-telegram-bot-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-telegram-bot-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import for the main bot class. While the README shows CommonJS, ESM is fully supported in recent Node.js versions.","symbol":"TelegramBot","correct":"import TelegramBot from 'node-telegram-bot-api';"},{"note":"CommonJS require pattern, commonly used in older Node.js projects or for direct `require` syntax. Avoid importing from internal `dist` paths.","wrong":"import TelegramBot from 'node-telegram-bot-api/dist/TelegramBot';","symbol":"TelegramBot","correct":"const TelegramBot = require('node-telegram-bot-api');"},{"note":"For TypeScript users, type definitions are typically installed separately via `@types/node-telegram-bot-api`. Import types using `import type` to avoid runtime overhead.","wrong":"import { Message } from 'node-telegram-bot-api';","symbol":"TelegramBot","correct":"import type { Message } from 'node-telegram-bot-api';"}],"quickstart":{"code":"import TelegramBot from 'node-telegram-bot-api';\n\n// Replace with your Telegram bot token obtained from @BotFather\nconst token = process.env.TELEGRAM_BOT_TOKEN ?? 'YOUR_TELEGRAM_BOT_TOKEN';\n\nif (token === 'YOUR_TELEGRAM_BOT_TOKEN') {\n  console.warn('WARNING: Replace YOUR_TELEGRAM_BOT_TOKEN with your actual bot token from @BotFather. You should use environment variables in production.');\n}\n\n// Create a bot instance using 'polling' for updates (suitable for development)\nconst bot = new TelegramBot(token, { polling: true });\n\n// Matches \"/echo [whatever]\" and sends it back\nbot.onText(/\\/echo (.+)/, (msg, match) => {\n  const chatId = msg.chat.id;\n  const resp = match[1]; // The captured \"whatever\"\n  bot.sendMessage(chatId, resp);\n  console.log(`Echoed '${resp}' to chat ${chatId}`);\n});\n\n// Listen for any kind of message and acknowledge it\nbot.on('message', (msg) => {\n  const chatId = msg.chat.id;\n  bot.sendMessage(chatId, 'Received your message!');\n  console.log(`Received message from chat ${chatId}: ${msg.text}`);\n});\n\nconsole.log('Bot is running and listening for messages...');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Major 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.","severity":"breaking","affected_versions":">=0.50.0"},{"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`.","message":"Hardcoding 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.","severity":"gotcha","affected_versions":">=0.12"},{"fix":"Install the type definitions as a development dependency: `npm install --save-dev @types/node-telegram-bot-api`.","message":"For 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.","severity":"gotcha","affected_versions":">=0.12"},{"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.","message":"Using '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.","severity":"gotcha","affected_versions":">=0.12"}],"env_vars":null,"search_vec":"'0.67.0':32 'activ':46 'align':50 'along':120 'api':4,12,24,40,54,93,163 'bot':3,11,23,39,92,106,152,160,162,164 'build':104 'cadenc':48 'chat':129 'choic':135 'client':5 'close':49 'command':119 'communiti':149 'community-support':148 'compat':58 'comprehens':15 'conveni':101 'current':29 'demonstr':44 'deploy':75 'develop':137,153 'differenti':82 'direct':85 'driven':112 'ensur':57 'environ':27 'event':111 'event-driven':110 'extens':87 'featur':55,145 'feature-rich':144 'flexibl':72 'foundat':134 'handl':113 'includ':34 'interact':18,130 'interfac':16 'javascript':157 'level':99 'librari':60,154 'long':63 'look':138 'low':98 'low-level':97 'maintain':30,143 'manag':128 'map':88 'media':126 'messag':116,125 'method':67,94 'need':79 'new':52 'node':9 'node-telegram-bot-api':8 'node.js':1,26,156 'offer':71,108 'offici':21 'packag':7 'poll':64 'primari':81 'provid':13,95 'receiv':69 'releas':47 'rich':146 'robust':35,109 'scalabl':78 'scenario':76 'send':124 'support':36,61,150 'telegram':2,10,22,38,53,91,105,151,158,159,161 'type':117 'updat':70 'util':122 'v8.1':43 'various':74,115 'version':31 'way':102 'webhook':66 'well':142 'well-maintain':141 'yet':100","created_at":"2026-04-20T01:55:41.959773+00:00","updated_at":"2026-04-20T01:55:41.959773+00:00","problems":[{"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.","cause":"The bot token provided during initialization is either incorrect, revoked, or has insufficient permissions.","error":"Error: ETELEGRAM: 401 Unauthorized"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'id')"},{"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.","cause":"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.","error":"Error: Polling error: Error: connect ECONNREFUSED"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/yagop/node-telegram-bot-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-telegram-bot-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}