node-red-contrib-telegrambot
Version:
Telegram bot nodes for Node-RED
70 lines (50 loc) • 4.24 kB
Markdown
# Overview
## What this is
`node-red-contrib-telegrambot` is a Node-RED plugin that exposes the Telegram Bot API as a set of flow-graph nodes. It lets Node-RED users build chat-driven automations (incoming messages, commands, callback queries, polls, payments, etc.) without writing JavaScript against the underlying HTTP API.
The project has been in continuous development since January 2016 (583 commits as of this snapshot). The current release is **V17.3.1**.
## Runtime model
The plugin runs **inside a single Node-RED process** as one of many installed contrib packages. It has no daemon, no separate worker, no IPC. Everything happens in the Node-RED event loop:
- A **config node** (`telegram bot`) holds the bot token, transport choice (polling / webhook / send-only), proxy settings, and an `http.Agent` (or `SocksProxyAgent`).
- Each runtime node (`receiver`, `sender`, `command`, `event`, `reply`, `control`) attaches to one config node and either subscribes to bot events or invokes bot methods.
- Telegram updates are pulled via long-poll **or** pushed to a built-in `https` listener (webhook mode).
- Outbound traffic is funnelled through a per-chat queue so messages to the same chat preserve order, while different chats run in parallel.
## Technology stack
| Layer | Choice | Notes |
|------|--------|------|
| Runtime | Node.js `>=14` | engines floor matches `socks-proxy-agent@8`'s requirement |
| Host platform | Node-RED `>=1.3.7` | declared in `package.json` |
| Telegram client | `node-telegram-bot-api@^0.66.0` | uses legacy `request@2.88.2` + `@cypress/request` transitively |
| Proxying | `socks-proxy-agent@^8.0.3` | optional; SOCKS4 / SOCKS4a / SOCKS5 |
| Promise extras | `bluebird@^3.7.2` | cancellation support enabled by `99-telegrambot.js` |
| Lint / format | ESLint 8, Prettier 2 | `quotes: warn` / `prettier: error` |
3 runtime dependencies, 5 dev dependencies; **218 packages** in the resolved `node_modules` tree.
## Package layout
```
telegrambot/
99-telegrambot.js (40 LOC) entry — registers node types with Node-RED
lib/
converter.js (756 LOC) Telegram update -> node msg.payload mapping
queue-manager.js (80 LOC) per-chatId FIFO with retry support
safe-stringify.js (15 LOC) JSON.stringify with [Circular] tolerance
nodes/
bot-node.js (1049 LOC) config node, lifecycle, polling / webhook
in-node.js (311 LOC) receiver, blob download, external-webhook input
out-node.js (984 LOC) sender, per-type switch (~50 cases), queue
command-node.js (280 LOC) /command routing + response capture
event-node.js (233 LOC) non-message updates (callback_query, polls...)
reply-node.js (148 LOC) onReplyToMessage capture
control-node.js (260 LOC) start / stop / restart of the bot
examples/ 49 sample flows shipped with the package
doc/architecture/ this documentation set
```
Total **4,156 LOC** of plugin code (excluding `node_modules`).
## Trust model
Two relevant boundaries:
1. **Editor-trusted**: anyone who can edit flows in Node-RED is implicitly trusted with bot config (token, allowlists, command regexes, etc.). Several config fields evaluate small expressions (`{flow.get(...)}`, `{env.get(...)}`) — the parser is whitelist-based (see ADR 0004).
2. **Telegram-untrusted**: incoming bot messages are treated as untrusted input. They are mapped into `msg.payload` by `converter.js` but never `eval`'d, never passed to `RegExp` constructors, never used as filesystem paths or method names on the bot instance.
## Distribution
Published to npm as `node-red-contrib-telegrambot`. Installed via Node-RED's palette manager. Releases are tagged `V<MAJOR>.<MINOR>.<PATCH>` on GitHub.
## Out of scope
- No tests are shipped — see [statistics.md](statistics.md). Test infrastructure is one of the highest-leverage future improvements ([recommendations-for-refactoring.md](recommendations-for-refactoring.md)).
- No TypeScript types are exposed.
- No separate worker process for downloads / heavy I/O — everything runs in the Node-RED main loop.