opensense
opensense

Telegram

Push alarms to a chat

Telegram is the most-used alarm channel in our customer base. It is free, instant, and a small café operator already has the app open on their phone.

Setup

  1. In OpenSense: Account → Integrations → Telegram → Link.
  2. The dialog shows a bot username (@opensense_bot) and a one-time linking code.
  3. Open Telegram. Search for the bot. Press Start. Send the linking code as a message.
  4. The bot replies "linked". The dialog in OpenSense flips to "active".

To add another chat (e.g. a group of operators):

  1. Add the bot to the group as a member.
  2. Send /link <code> in the group, where <code> is the per-site linking code from the dashboard.
  3. The bot confirms.

A group chat is recommended when an alarm should wake up more than one person.

Per-channel routing

For sites with many devices, you may not want every alarm to ping every operator. Route per channel:

PATCH /v1/channels/chn_a1b2/notifications
{
  "telegram_targets": ["@nightmgr", "@daymgr"],
  "telegram_digest": { "min_interval_min": 10 }
}

telegram_digest.min_interval_min is the minimum gap between consecutive notifications for the same channel. Different channels are not rate-limited against each other.

Rate limiting

OpenSense rate-limits per-chat at 1 message per 10 s (Telegram Bot API caps at 1/s; we add headroom for groups). Excess goes into a queue visible in the dashboard's Outbound log; messages older than 2 minutes are dropped with a single "queue overflow" summary instead.

To avoid flooding during a cascading failure (door propped open, 12 channels in alarm), configure a digest:

PATCH /v1/sites/site_4f3c/notifications
{
  "digest": {
    "enabled": true,
    "min_interval_min": 30,
    "summary_only": true
  }
}

A site-wide digest collapses multiple channel alarms in the same window into one summary message. Auditors prefer this; chasing 12 identical messages is operator fatigue, not information.

Message format

A typical alarm message:

🔴 ALARM
Kava Bratislava · walk-in fridge
T = +11.2 °C  (allowed -2 to +8 °C)
opened 08:10 · 4 min ago
ack: https://opensense.murzin.digital/app/e/evt_4f3c

Tap the link to ack inline. The browser opens a tiny ack page that sets the cookie; one tap on the "Acknowledged" button records the ack. No separate app to install.

What you give up

  • No two-way command-and-control. The bot listens for /link, /ack and /silence; it does not let you rotate tokens or edit rules from Telegram.
  • Telegram-hosted. If Telegram is blocked in your jurisdiction, use email or webhook instead.
  • No end-to-end encryption between us and your operator (Telegram Bot API uses MTProto-on-TLS but is not E2E). Do not put highly-sensitive content in the alarm body; the alarm is a signal, not a payload.