Telegram Notifications
A pure-notifier service the backend calls on threats and health events, with self-service subscriber registration via a Telegram Bot and a dry-run mode for testing without sending real messages.
What was asked
Implement a Telegram notification feature with a Telegram Bot that informs team members about infrastructure health events and detected threats.
Design
The service is deliberately kept simple: it does not decide what is worth notifying about — the backend does that — it only knows how to deliver a message. This keeps threat classification logic in one place (the backend) and the notifier reusable for other event sources, including the monitoring alert rules in Task 5, which point at the same Telegram chat as a contact point.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /notify | Body: {type, source, message, detections?, event_id?, timestamp?}. Sends a Telegram message. |
| GET | /healthz | Returns {status, configured, subscribers_count, subscribers} — configured is false in dry-run. |
Subscriber management
A background task runs Telegram long-polling for /start commands, so team
members subscribe themselves by messaging the bot — no manual chat-ID configuration needed
per person.
Dry-run vs. real delivery
With no TELEGRAM_BOT_TOKEN set, the service runs in dry-run: it logs the
message instead of sending it, which is what makes local/CI testing possible without a real
bot token or hitting Telegram's API. Providing the token via the telegram-credentials
Kubernetes Secret switches it to real delivery.
| Variable | Meaning |
|---|---|
TELEGRAM_BOT_TOKEN | bot token from @BotFather — empty means dry-run |
TELEGRAM_CHAT_ID | optional fallback target chat id; comma-separated for several |
Where it sits in the flow
On a THREAT-type event, the backend fires a background, fire-and-forget
POST /notify — see the full sequence in
System Architecture. Deployed on-cluster alongside the
backend and frontend, though whether it strictly needs to run on Kubernetes (versus as a
standalone service) is noted in the project tracker as a still-open decision — it works
either way, and keeping it on-cluster was the simpler default.
Deploy
cd cluster
make up-step4
make telegram-logs