Skip to content

Deprecated — Consolidated into OBS-0001 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in OBS-0001.

ADR-0009: Telegram over WhatsApp for platform alerting

Status

Accepted — 2026-04-02

Context

Platform requires push alerting for: Uptime Kuma, NetAlertX, Diun, Grafana OT thresholds, future Wazuh SIEM. Telegram and WhatsApp evaluated.

Decision

Telegram via @caneast-alertbot using the official Bot API.

Rationale

  • Free, no business account, no per-message cost
  • Bot creation via @BotFather in 2 minutes, works behind NAT
  • WhatsApp requires Meta Business verification + paid Cloud API or unofficial libraries that violate ToS and break on updates
  • Native integrations in Grafana, Uptime Kuma, Diun, Wazuh
  • Bot token stored in Infisical at caneast/prod/telegram/bot-token

Forward-looking note

  • WhatsApp: Will be implemented as a family-facing alert channel so household members receive critical notifications (flood, power, security) without needing Telegram. WhatsApp Business API becomes justified once the audience extends beyond the platform operator.
  • FreePBX / Asterisk SMS: Planned as an additional alerting path via SIP trunk SMS for delivery to family members who may not check app notifications. Provides a carrier-level fallback independent of internet-based messaging.

For internal platform operations, Telegram remains the primary channel.

Consequences

  • All platform alerting integrations standardize on Telegram Bot API
  • WhatsApp added in a future phase for family-facing critical alerts
  • FreePBX/Asterisk SMS added as carrier-level fallback for family notifications
  • Other channels (email, PagerDuty, Slack) are secondary only

Supplement (2026-05-12): Bot Architecture - Alerting vs ChatOps

Two Telegram bots serve distinct roles on the platform. These roles must not cross.

SentinelBot (@caneast-alertbot) - ALERTING only

  • Receives push notifications from Alertmanager via the Telegram receiver (this ADR, WI-329)
  • One-way: platform pushes to the operator. No command handling.
  • Routing: Alertmanager sends to SentinelBot. No other service sends to SentinelBot.

ArchonBot / archonagent - CHATOPS only

  • Receives natural language queries from the operator
  • Routes to OpenClaw on CanEast AI Node WSL at port 18789
  • One-way: operator queries the platform. No alert delivery via this bot.

Routing rule: Alertmanager sends only to SentinelBot. archonagent queries only OpenClaw. No crossover between these roles.

Future bots: Any new Telegram bot introduced to the platform must declare its role (ALERTING or CHATOPS) in its ADR and must not perform functions belonging to the other role.