Telegram
Telegram is how lanowl reaches you: alerts, digests, the weekly review, proposals with their Approve and Reject buttons, and answers to your questions. It uses a bot of its own, which only talks to your chat.
Make the bot
In Telegram, open a chat with @BotFather, send /newbot, and follow its two questions (a
display name, then a username ending in bot). BotFather answers with a token like
123456:ABC-DEF….
Give it to lanowl
On the dashboard, in the first-run setup's Telegram step. Later, the same step is in Settings → Add from the router's list (Use another bot or chat); Settings → Secrets replaces the token alone, and keeps the chat.
- Paste the token and Check the token: lanowl asks Telegram which bot it is and shows its name.
- From the phone you want the alerts on, send
/startto your bot. The page lists the chat that wrote, within seconds (it listens for five minutes). - Use this chat: the bot says hello there, and the setup's last step writes the token into
secrets.yaml(never shown again) and the chat intoconfig.yaml(telegram.chat_id).
The settings that go with it, in config.yaml (Settings → Telegram):
telegram:
chat_id: "100000001"
chat:
enabled: true # answer questions and /commands
allowed_chat_ids: [] # empty: only chat_id
By hand
The token goes in config/secrets.yaml:
tokens:
telegram: "123456:ABC-DEF..."
or in the environment as LANOWL_TG_TOKEN (or LANOWL_TG_TOKEN_FILE, a file holding it,
which is how Docker secrets arrive). For the chat id, before lanowl runs: send /start to the
bot, open https://api.telegram.org/bot<token>/getUpdates in a browser, and find
"chat":{"id":…. Once lanowl runs, it reads the bot's updates itself, and a second reader
gets an error instead (lanowl logs it as "another client is polling this bot").
Who is listened to
Only the chats in telegram.chat.allowed_chat_ids (by default, chat_id alone) are
answered. A message from anyone else is ignored and logged once per chat; the bot never
replies to strangers, because everything it says comes from your network.
The Approve and Reject buttons are pressed by a person, not a chat. In your private chat with
the bot, your chat id is your user id, so nothing more is needed. In a group, anyone in
it could press them: list who may in telegram.chat.allowed_user_ids.
What arrives, and when
| Message | When |
|---|---|
| 🔴 CRITICAL | At once, for a device of criticality: critical, a whole group gone dark, or the internet. One per incident. |
| 🟢 RECOVERED | When it has stayed fine for 15 minutes (alerts.recovery_confirm_s), with how long it lasted. |
| ⚪🟡🟠 lanowl digest | After the hourly audit, only when something new opened that is not critical, or the owl's reviews found something. Never "all is well". |
| 📜 Proposals | A fix the owl proposes, with Approve and Reject. On the incident's own alert when there is one. |
| 🛡 Updates and security | After the morning check, only what is new and matters. |
| 🆕 New device | A device never seen on your router's DHCP before: listed when it joins (discovery.notify_new_devices), and once more with the owl's reading when it thought it worth a word. |
| 📅 Week in review | Sundays at 10:00 (weekly). |
How the gate decides what is worth a message: How alerts work.
When the internet is down
An alert that cannot leave the network is kept in an outbox (telegram.outbox_file, kept
across restarts) and sent, in order, as soon as the internet answers again, marked
"⏳ delayed delivery" with the time it was queued. One about something that has meanwhile
recovered says that too.
Commands
Send /help for the list. The full reference: Telegram commands.
Anything that is not a command is a question for the owl: Asking the owl.
Edit this page on GitHub.