The notification plane — pushes trade confirmations, AI market briefs, and kill-switch alerts to Telegram. Also listens: copilot commands, RAG queries, operator chat.
Part of the HOOX edge-trading mesh — a production-grade algorithmic trading framework on Cloudflare Workers.
Site: hoox.sh · Docs: docs.hoox.sh · Paper: hoox-arxiv-paper-core.pdf
The telegram-worker is the bi-directional notification hub for the HOOX mesh. Six workers — hoox, trade-worker, agent-worker, report-worker, web3-wallet-worker, and email-worker — fire notifications through its service binding. Outbound messages (trade confirmations, AI-generated market summaries, emergency risk alerts, PDF delivery notices) are sent via the Telegram Bot API to configured chat_id targets.
Inbound, the worker processes Telegram commands (/ask, /search) with optional Workers AI summarization and RAG context retrieval through Cloudflare Vectorize (my-rag-index). Embeddings are generated on-the-fly and queried against the RAG index for context-aware responses.
hoox ─────────┐
trade-worker ─┤
agent-worker ─┤
report-worker ─┼──► telegram-worker ──► Telegram Bot API
email-worker ─┤ │
web3-wallet ──┘ │
├──► Workers AI (summarization)
├──► Vectorize (RAG context)
└──► R2 (media/shared files)
| Direction | Worker | Binding |
|---|---|---|
| Inbound (callers) | hoox, trade-worker, agent-worker, report-worker, web3-wallet-worker, email-worker |
TELEGRAM_SERVICE |
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/alert |
X-Internal-Auth-Key (fail-closed) |
Primary notification endpoint (service binding) |
POST |
/process |
X-Internal-Auth-Key (fail-closed) |
Legacy alias for /alert (same handler) |
POST |
/webhook |
X-Telegram-Bot-Api-Secret-Token + chat allowlist |
Telegram Bot API ingress (commands, RAG, photos) |
GET |
/health |
None | Liveness probe |
- Trade confirmations: structured order summaries with symbol, side, qty, price, fill time
- AI briefs: portfolio summaries generated via Workers AI, routed through configured model
- Kill-switch alerts: immediate push when agent-worker engages global circuit breaker
- RAG queries:
/askcommands search Vectorize index for context-aware responses - PDF delivery: report-worker fires notification on new R2 report generation
- Embeddings: on-the-fly text embedding generation for semantic search
bun test workers/telegram-worker| Secret | Role |
|---|---|
TG_BOT_TOKEN_BINDING |
Bot API token |
TG_CHAT_ID_BINDING |
Default destination when chatId omitted |
TELEGRAM_SECRET_TOKEN |
Telegram webhook header secret (fail-closed) |
INTERNAL_KEY_BINDING |
Mesh X-Internal-Auth-Key for /alert |
AUTHORIZED_CHAT_IDS |
Comma-separated IDs; inbound /webhook fail-closed when unset; outbound /alert allowlist (else only TG_CHAT_ID_BINDING) |
Align AUTHORIZED_CHAT_IDS with gateway TELEGRAM_ALLOWED_CHAT_IDS. Local: copy .dev.vars.example → .dev.vars.
| Direction | Peers |
|---|---|
| Called by | hoox-worker, trade-worker, agent-worker, report-worker, web3-wallet-worker, email-worker. |
| This worker calls | See list below |
- analytics-worker — ANALYTICS_SERVICE — delivery telemetry
Full mesh (all isolates live as git submodules under hoox-sh/hoox workers/):
| Isolate | Role | Repository |
|---|---|---|
| hoox-worker | Public webhook gateway (WAF, idempotency, dispatch) | monorepo workers/hoox-worker |
| trade-worker | Multi-exchange order execution (Binance / Bybit / MEXC) | monorepo workers/trade-worker |
| agent-worker | AI risk manager (configurable cron 1–1440 min, kill switch) | monorepo workers/agent-worker |
| d1-worker | D1 SQL proxy + settings / balances / positions | monorepo workers/d1-worker |
| telegram-worker | Alerts, bot commands, RAG copilot | monorepo workers/telegram-worker |
| email-worker | Mailgun / email signal parsing → trade | monorepo workers/email-worker |
| analytics-worker | Analytics Engine write + query path | monorepo workers/analytics-worker |
| report-worker | PDF reports via Browser Rendering → R2 | monorepo workers/report-worker |
| web3-wallet-worker | On-chain wallet identity (ethers.js) | monorepo workers/web3-wallet-worker |
| dashboard | Next.js ops console (OpenNext, public) | monorepo workers/dashboard |
| Resource | Link |
|---|---|
| Isolate profile (operators) | https://docs.hoox.sh/docs/devops/workers/telegram-worker |
| Parent monorepo | github.com/hoox-sh/hoox |
| This repository | github.com/hoox-sh/telegram-worker |
| Workers index | docs.hoox.sh → Workers |
| CLI | @hoox-sh/hoox-cli · hoox deploy worker telegram-worker |
CC BY 4.0 — part of the HOOX open-core mesh.