Notifications and alerts
Notifications and alerts
A notification is a message to one person: a task assigned to you, a renewal falling due, an approval waiting on you. An alert destination is a named place that is not a person, such as an on-call group chat or a shared mailbox, that monitors and reports also send to.
How a notification travels
Modules do not send messages themselves. They hand a notification to the core, which:
- records it first, in your inbox. The record is the notification. If every delivery fails, it is still there when you look;
- then tries to reach you on each channel you have turned on, and records what each channel did.
Each notification has a kind, named after the module that sent it, such as tasks.assigned. Your inbox shows it under the title.
Channels: how notifications reach you
A channel is offered by a module, so the channels you see depend on what is installed:
| Channel | Offered by | What you do |
|---|---|---|
| Telegram | Comms | Link your Telegram account with a one-time code sent to the bot |
| Nothing: it uses your account's address. An operator must first designate a mailbox to send from | ||
| Browser push | Push devices | Press Allow notifications on each browser you want them on |
On Notifications (the bell in the top bar), under Where these reach you, you can:
- turn each channel on or off. A channel that is not set up yet says why and cannot be ticked;
- set quiet hours for a channel. Quiet hours hold a notification rather than drop it: it is still in your inbox.
A channel from a module that is switched off is skipped, not counted as a failure.
The daily digest
A digest is one summary of what you have not read in the last day, sent through your channels. A channel can carry a digest hour, a local hour in your own time zone, and the digest goes out at that hour only when something is unread. On main the Notifications screen does not set the digest hour; it is set through PATCH /api/notifications/channels/<channel> with digestHour. The hourly check that sends due digests belongs to the Reminders module, so digests need Reminders installed.
You can also ask for one now: an agent with core.sendDigest sends you a summary of the last hours you name (over MCP, core__sendDigest). Nothing is sent when nothing is unread.
Alert destinations
Some messages belong to a place rather than a person: a site going down should reach the on-call room, whoever is on call. Notifications → Where alerts go holds these named destinations.
- Press Add destination.
- Give it a Name, such as "on-call".
- Pick a Kind: Telegram (a group chat, carried by Comms) or email (an address, carried by Mail). Only kinds an installed module can reach are offered.
- Fill in the chat id or address. For Telegram, Send through picks which bot carries it, or the default bot.
- Press Add. On the destination, Send a test sends a test message and shows the result beside it; Delete removes it.
Monitors and scheduled reports send to destinations as well as to whoever they belong to. Deleting a destination means anything still sending there reaches nobody.
Destinations need their own permissions, because changing a chat id silently redirects every alert:
| Permission | Lets you |
|---|---|
notifications:read | See where alerts are sent |
notifications:manage | Add, change, test and delete destinations |
Agents and your inbox
Reading and clearing your own inbox on the screen needs no permission. Letting a tool do it for you, an agent or an API key, needs notifications:inbox, because handing over your inbox should be your choice. The core's tools for this are core.listNotifications, core.markNotificationRead, core.markAllNotificationsRead and core.sendDigest. Destinations have core.listTargets, core.targetKinds, core.targetDeliveries, core.createTarget, core.updateTarget, core.testTarget and core.removeTarget.