Set a rule on a field and Dialect opens an alert when it holds, tells people, and closes the alert when a reading shows it’s over. At the end the right people hear about what matters.
Set rules
PUT replaces all of an endpoint’s rules and runs at once, with no confirming.
| Rule | For |
|---|---|
{"field": "valve", "is": ["open"]} | choice, yes_no, level and colour fields |
{"field": "pressure", "above": 70} | number fields |
{"field": "pressure", "below": 20} | number fields |
text fields can’t have rules. An endpoint can have up to 20.
| Option | Means |
|---|---|
for_s | How long it must hold before opening, 0 to 86,400. At least every_s when not 0 |
clear_for_s | How long it must be over before closing, 0 to 3,600 |
if_no_sure_value_for_s | Also open if the field has had no sure value this long, 600 to 86,400. At least two reads |
priority | low, high (default) or urgent |
remind_every_s | Remind while open and unclaimed, 300 to 86,400 |
ends_below, ends_above | On above or below: where it ends, so a reading near the line doesn’t flap |
Call GET /v1/endpoints/{name}/alerts to check. You should see each rule with its rule key, such as pressure:above:70 or valve:is:open, and its sentence, such as Pressure is above 70 psi (ends below 68).
Know how alerts behave
- Only sure readings open or close an alert, except that
if_no_sure_value_for_sopens one with no value. A sure reading then closes it like any other. - An unsure reading pauses the clock on
for_sandclear_for_s, and never resets it. Setif_no_sure_value_for_sto hear about it when that lasts. - Silence never closes an alert. A reading does, or pausing or stopping the endpoint, or removing the rule.
- Alerts are held back while the gateway has been silent for over 2 minutes, with
inhibited_by: "gateway_silent".
See alerts
state is pending, open or closed. By default you get pending and open. Closed gives the latest 50. You should see:
close_reason is reading, endpoint_paused, endpoint_stopped or rule_removed. A pending alert’s progress says how far along it is, such as Above 70 psi for 40 of 120 s.
Claim an alert
Say someone’s on it. The first claim wins, later calls add a note, and claiming never closes it. Reminders stop while a claim is current.
The alert’s handling then holds the claim.
- A note can be up to 500 characters.
- A claim goes stale after 2 hours with no note while the alert is open, and reminders resume.
- An
urgentalert unclaimed 15 minutes after people were told escalates once: administrators are emailed and analert.escalatedwebhook goes out. Onlyurgentalerts escalate.
Shelve a rule
During planned work, stop a rule telling anyone for up to 24 hours. Its alerts keep opening and closing. One still open when the shelf ends is told as if it had just opened.
DELETE on the same path takes it off the shelf.
Get told
- In the console: open alerts show under Needs you. An endpoint with no rules adds nothing there.
- By email: off by default for each endpoint.
PUT /v1/endpoints/{name}/email-alertswith{"on": true, "recipients": [...]}turns it on, with people’s identity IDs asrecipients.GETon the same path lists who can receive them underpeople. Alerts close together are batched, within 30 seconds and up to 25 to an email. - By webhook:
alert.opened,alert.closed,alert.handled,alert.shelvedandalert.escalated. See Webhooks.
Watch for gateway alerts
Dialect opens these itself. They appear in GET /v1/alerts, and administrators are emailed. They can’t be claimed, shelved or escalated.
kind | Opens when | Closes when |
|---|---|---|
gateway_offline | A gateway in use has been silent for 5 minutes | It’s heard again (heard), or says it stopped (stopped) |
gateway_health | A problem such as disk_low or hot has held for 10 minutes | It has been clear as long (cleared) |
Their endpoint, field and rule are null. A gateway stopped on purpose opens no alert.