Registry /
communication / node-red-contrib-telegrambot
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Telegram Bot (Configuration)
✓ Install 'node-red-contrib-telegrambot' via Node-RED Palette Manager. Drag a 'Telegram Bot' config node from the palette onto the workspace.
This package is a Node-RED contribution. Functionality is exposed via visual nodes in the Node-RED editor, not through direct JavaScript `import` or `require` statements. The 'Telegram Bot' configuration node is central for token setup.
Telegram Receiver Node
✓ Install 'node-red-contrib-telegrambot'. Drag a 'Telegram Receiver' node from the palette onto the workspace.
This node listens for incoming messages and events from your configured Telegram bot, pushing them as `msg` objects into your Node-RED flows.
Telegram Sender Node
✓ Install 'node-red-contrib-telegrambot'. Drag a 'Telegram Sender' node from the palette onto the workspace.
This node sends messages, photos, documents, or other actions to Telegram chats. It expects an incoming `msg` object formatted with `chatId`, `type`, and `content`.
This Node-RED flow demonstrates a simple Telegram echo bot. It receives text messages, logs them to the debug sidebar, and then sends back the received message content prefixed with 'You said: ' to the same chat. Remember to replace 'process.env.TELEGRAM_BOT_TOKEN ?? ''' with your actual bot token, ideally stored in an environment variable for security, within the 'MyTelegramBot' configuration node.
[
{
"id": "e7b0d1e2.123456",
"type": "tab",
"label": "Telegram Echo Bot Example",
"disabled": false,
"info": "This flow demonstrates a basic Telegram echo bot using node-red-contrib-telegrambot."
},
{
"id": "a1b2c3d4.789012",
"type": "telegrambot-config",
"name": "MyTelegramBot",
"bottoken": "process.env.TELEGRAM_BOT_TOKEN ?? ''",
"polling": "true",
"filter_chats": "",
"filter_users": "",
"filter_events": "text,command",
"store_user_profile": "false",
"x": 200,
"y": 100,
"wires": []
},
{
"id": "f5e6d7c8.123456",
"type": "telegram receiver",
"name": "Telegram Receiver",
"bot": "a1b2c3d4.789012",
"x": 200,
"y": 200,
"wires": [
["g9h0i1j2.789012", "k3l4m5n6.789012"]
]
},
{
"id": "g9h0i1j2.789012",
"type": "debug",
"name": "Received Message",
"topic": "",
"payload": "payload",
"payloadType": "msg",
"status": "",
"x": 450,
"y": 160,
"wires": []
},
{
"id": "k3l4m5n6.789012",
"type": "function",
"name": "Echo Message",
"func": "msg.payload = {\n chatId: msg.payload.chatId,\n type: 'message',\n content: `You said: ${msg.payload.content}`\n};\nreturn msg;",
"outputs": 1,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 430,
"y": 240,
"wires": [
["o7p8q9r0.123456"]
]
},
{
"id": "o7p8q9r0.123456",
"type": "telegram sender",
"name": "Telegram Sender",
"bot": "a1b2c3d4.789012",
"x": 660,
"y": 240,
"wires": [
[]
]
}
]
Debug
Known issues
breakingWith version 17.0.0, the dedicated 'Callback Query' node was replaced by the more general 'Event' node. Existing flows using the old node will need to be updated to use the new 'Event' node, configured to listen for 'callback_query' events.fixReplace old 'Callback Query' nodes with the new 'Event' node and configure it to receive 'callback_query' events.
affects: >=17.0.0
breakingUsers running Node-RED 19+ (which often includes Node.js v22) may encounter 'AggregateError' and 'RequestError' leading to Telegram send failures. This is related to changes in network handling within Node.js v22 affecting how the underlying Telegram API library operates, potentially causing polling issues with Telegram servers.fixConsult the package's GitHub issues for potential workarounds or specific version recommendations for Node.js. Downgrading Node.js to v18 might resolve the issue temporarily.
affects: >=17.x.x (when used with Node-RED 19+ and Node.js v22)
gotchaVersion 17.1.0 introduced significant changes to how messages are enqueued and processed, particularly concerning flood control (Telegram API Error 429). Messages are now processed sequentially by `chatId`, and the queue will pause if a flood error occurs. This alters message delivery behavior, which might affect flows relying on immediate or parallel processing.fixReview existing flows for any time-sensitive message sending logic or scenarios that might be impacted by sequential processing and potential pauses. Ensure your bot logic can gracefully handle message delivery delays.
affects: >=17.1.0
gotchaWhile this package itself has not been flagged for direct vulnerabilities by Snyk, the broader ecosystem around the underlying `node-telegram-bot-api` library has seen supply chain attacks where malicious npm packages mimicked legitimate ones to plant SSH backdoors. Always verify the authenticity of Node-RED packages before installation.fixOnly install packages from trusted sources. Regularly audit your Node-RED instance and its dependencies for suspicious activity. Consider using Node-RED's official 'Manage palette' for installation.
affects: All versions
gotchaTelegram bot tokens are sensitive credentials. Never hardcode them directly into your flows or commit them to public version control. Using environment variables is the recommended secure practice. Additionally, consider regularly rotating your bot tokens.fixStore your Telegram bot token in an environment variable (e.g., `TELEGRAM_BOT_TOKEN`) and reference it in the 'Telegram Bot' configuration node as `process.env.TELEGRAM_BOT_TOKEN`.
affects: All versions
Errors
Common errors & fixes
AggregateError: All promises were rejected
at new RequestError
Compatibility issues between Node.js v22 (often bundled with Node-RED 19+) and the underlying HTTP request library used by node-red-contrib-telegrambot, particularly affecting outbound requests to Telegram's API.
fixCheck for updates to `node-red-contrib-telegrambot` that specifically address Node.js v22 compatibility. If no update is available, consider downgrading your Node.js version to v18 or checking GitHub issues for manual patches/workarounds.
Error 429: Too Many Requests
Your Telegram bot is sending messages too frequently, exceeding Telegram's API rate limits.
fixThe package includes internal flood control mechanisms (since v17.1.0) to pause sending when this error occurs. However, review your flow logic to reduce message frequency if possible, especially for broadcast or rapid response scenarios.
Telegram Receiver node not appearing in palette after installation.
The package might not have been installed correctly, or Node-RED did not restart/reload its palette. Incorrect Node.js or Node-RED versions can also prevent nodes from loading. The package requires Node.js >=12.0.0 and Node-RED >=1.3.7.
fixEnsure `node-red-contrib-telegrambot` is listed in your `~/.node-red/package.json`. Try restarting Node-RED. Verify your Node.js version (`node -v`) and Node-RED version. Reinstall the package using Node-RED's 'Manage palette' functionality or via `npm install node-red-contrib-telegrambot --save` in your Node-RED user directory.
Audit
Dependencies
No dependency data recorded yet.