Besides alarm rules, two tools send notifications: the Tell people action of a Rules-card rule, and the Notify block of a flow. Both go through the same notification service as alarms, with the same channels and personal preferences. They add a cooldown so a repeated event does not flood people.
From a Rules-card rule
The action Tell people has two fields:
| Field | Meaning |
|---|---|
| Who | Tick Owners, Admins and/or Members. |
| Message | Up to 1,000 characters. |
- The notification’s title is the rule’s name; its text is the message.
- Users, roles, custom roles and teams are reached in the app, by push where it is set up, and in linked chat apps; they never get e-mail or SMS. Only
addressrows get e-mail and onlyphonerows get SMS. - In the card you choose roles. The rules API also accepts single users (
{ "kind": "user", "userId": "…" }) and teams ({ "kind": "team", "teamId": "…" }), up to 20 recipients, and achannelslist. - A role or team with more than 20 active members is refused rather than half-told, and the run records the failure.
- Members are reached in the bell, by push and in their chat apps. The Rules card cannot name e-mail addresses or phone numbers; use a flow for those.
- Tell people keeps working in Manual only if the rule is marked Also runs in Manual.
{ "id": "a3", "kind": "notify", "recipients": [ { "kind": "role", "role": "ADMIN" }, { "kind": "team", "teamId": "…" } ], "channels": ["inapp"], "text": "Cold room door open for 10 minutes" }See Rules card: actions.
From a flow: the Notify block
The Notify block sends to users, roles, teams, e-mail addresses and phone numbers, and passes the message on.
| Setting | Meaning | Limits |
|---|---|---|
| recipients | Rows of a kind and a value: user (a user id), address (one or more e-mail addresses, comma-separated), phone (numbers in international form), role (OWNER, ADMIN, USER), custom_role, team, or originator_owner (the owners of the message’s originator, where a module declares them). Values are templates. | 20 rows; 20 recipients after expansion |
| channels | Restrict to these channel ids. Empty: each recipient’s own choice. | |
| urgency | normal or critical. Critical skips recipients’ preferences unless the organisation switched that off. | |
| title, text | The message, as templates. | 200 and 4,000 characters |
| format | text, or html for mail (other channels get plain text). | |
| subject, reply_to, cc, bcc | Mail options. Each cc and bcc address gets its own message. | |
| attachments | Files for the mail. | 10 files, 1 MiB together |
| reason | What makes two notifications “the same” for the cooldown. | 200 characters |
Full block reference: Alarm, command and notify blocks.
Templates
Values in {{ }} are filled from the message, for example:
title: {{ msg.metadata.deviceName }}: level {{ msg.payload.level }} %
text: Tank level fell below the limit at {{ msg.metadata.deviceName }}.A value inserted into an HTML text is escaped, so a message can add text to the mail but never markup.
The cooldown
A repeated event must not send hundreds of messages. Each recipient gets a notification of the same reason from the same flow once per cooldown: 10 minutes, unless your plan sets another (at least 1 minute).
- The reason is the block’s
reasonsetting, or, without it, the words of the notification. A text that changes with every reading (“Level 41 %”, “Level 40 %”) is a new reason each time; setreason(for examplelevel of {{ msg.metadata.deviceName }}) to fold them. - A held-back recipient is left out; the others still get it. When nobody is left, the message goes on without error.
- The next notification after the cooldown ends with “(+n)”: how many were held back meanwhile.
- A recipient counts as told only when a channel delivered. If every channel failed or was held back by preferences or quiet hours, the next notification goes out to them.
- The Rules card’s Tell people is a flow block underneath, so it has the same cooldown, keyed on the rule’s name and message.
Late messages
A message processed after its time-to-live (after an outage) notifies nobody: readings hours old should not page people. It is counted as “too old”.
Quotas
Before sending, the block checks the monthly e-mail and SMS quotas of the channels it would use. A channel without quota (or not in the plan) is left out and named in the result; the others still go out. Only when every channel is out of quota does the block end with the error limit.
The result
The message goes on with msg.metadata.notify:
| Field | Meaning |
|---|---|
recipients | How many recipients were addressed |
delivered / failed | Channels delivered / failed |
suppressed | Channels held back by a preference, quiet hours or a blocked address |
invalid | Entries that were not a valid user id, address or number |
quota | Channels left out for quota |
held | Recipients held back by the cooldown |
Errors: no_recipients, too_many_recipients, members_unavailable, invalid_attachment, notify_failed (every delivery failed), limit.
Which to use
| Need | Use |
|---|---|
| Tell people when an alarm opens, with reminders and storm protection | The alarm rule’s notify block. Alarm notifications in depth |
| Tell a role about something a rule did | Tell people |
| Mail with attachments, SMS, an outside mailbox, custom text from data | The flow Notify block |