Channels and levels
A channel is where an alert goes, and every channel is a URL. Anything that can make an HTTP request can send to it: a probe or a vital of ours, Grafana, a CI job, Home Assistant, a line of shell. The channel decides how loud a message is allowed to be, who it reaches, and when it should keep quiet.
What a sender can put in a message is on Sending alerts. Who a page goes to on a team is on On call.
Making one
Make a channel under Channels in the web app, from the Channels tab in Mast Pager, over the API, or from a YAML file. Whichever you use, it asks for three things:
- name: letters, digits, dot, underscore, hyphen and spaces, up to 32 characters, starting with a letter or digit.
- kind: a Channel receives messages when something happens; a Vital expects a heartbeat, and silence is the alert. A new vital starts at every hour with ten minutes of grace.
- default priority: quiet, normal, loud or page. This also sets the channel's ceiling, so only a channel created at Page can carry a page.
Creating it hands you the key card: the send address as text and as a QR code, with Copy and Share, and a curl line to paste. For a vital the line is curl -fsS on the end of a crontab entry. Send a test page sends at the channel's ceiling so you hear what the loudest thing this channel can do sounds like; on a vital the test doesn't count as a beat.
The address is the secret
The URL is the whole credential for one channel. Anything holding it can send to that channel, and nothing else; it can't read the feed, make channels or reach any other channel. Keep it wherever you keep other secrets. If it leaks, someone can fill your feed, but they can't make the phone ring louder than the ceiling you set, and Rotate key on the channel's page replaces it in one tap. The old key keeps working for seven days, so there's time to update whatever sends with it, unless you're at your plan's key cap, when it stops at once. If you think someone else has the address, This isn't mine on a message cuts the old key off immediately. Delivery has that one.
A channel's settings
Open a channel and every setting is a row. The web app and the app show the same ones:
| Row | Choices | Notes |
|---|---|---|
| Default priority | quiet / normal / loud / page | What a send gets when it names no level |
| Highest priority | quiet / normal / loud / page | The ceiling. A send asking for more gets this. Lowering it below the default lowers the default too |
| Sound | default, bleep, chirp, rising, pager, klaxon | Tap a tone to hear it. A send that names its own tone wins |
| Quiet hours | off, or from / until | Inside the window this channel arrives silently. Pages are the exception |
| During a pause | quiet / still sounds | Whether a phone-wide pause holds this channel's pages |
| Escalation | none, or a policy | Web app only. Which people a page goes to, in what order. On call |
| Escalation partner | never, or after 2 / 5 / 10 / 30 min | Where an unacknowledged page goes next. A second phone |
| Mute | not muted, 15 min, 1 h, 4 h, until 8:00 tomorrow | Silence in a hurry. Pages are the exception |
| Repeat | once, or every 1 / 2 / 5 min | How often a page comes back while nobody has acknowledged it |
| Expire | 15 min, 1 h, 4 h, 1 day, never | When a page stops repeating and stays in the feed as one nobody answered |
| Dedupe window | off, 1 / 5 / 15 min, 1 h | Folds an identical message into the one already there and counts it. Channels only |
| Storm threshold | never, or 10 / 20 / 50 in five minutes | A channel that floods collapses into one row with a count. Channels only |
A vital has three rows of its own instead of dedupe and storm: Heartbeat period (5 min, 15 min, an hour, 6 hours, a day), Grace, and When it stops, which is the level a missed heartbeat pages at. Crontab schedules and run limits are set in the web app or over the API, and the phone shows them read-only. Vitals has them.
At the foot of every channel: Send a test, Rotate key, Delete channel. Deleting stops the address at once; messages already in the feed stay until they age out of retention.
Neither a dedupe window nor a storm threshold ever collapses a page. A pager that swallowed the second page because it looked like the first has lied to you once, and you wouldn't know which time.
The list on the phone
The Channels tab is two sections, vitals and channels, each row with a one-line summary: pages, escalates to Sam, quiet hours 22–07, muted until 14:10, 3 today. Swipe right on a row to Mute 1h (or Unmute); swipe left to Delete, behind a confirmation. Neither fires on a full swipe. Pull the row and the button waits to be tapped.
Levels
Every message carries one of four levels. A level isn't a score for how bad something is; it decides what the phone does and who gets interrupted.
| Level | What the phone does |
|---|---|
| quiet | Into the feed and the notification list. No sound, no banner, no lit screen |
| normal | A banner and a sound, held by the ringer switch, by a Focus and by the channel's quiet hours |
| loud | Time-sensitive, so it arrives during a Focus. Once, with no repeat |
| page | Re-alerts every two minutes until somebody acknowledges it, then moves to a second phone if the channel names one |
Three questions pick a level, in order, stopping at the first no. Does a person have to do something? If not, quiet or normal. Does it have to be today? If it can wait for morning, normal, and quiet hours will hold it there. Would you rather be woken than find it at breakfast? Yes is a page. No is loud.
The cost of over-paging isn't the noise. It's that the next real page arrives at a phone you've already taught yourself to ignore.
The ceiling
A sender can ask for any level it likes. Asking for more than the channel's ceiling gets the ceiling, and the feed shows both: asked for page · sent loud. A channel made in the app can be given any ceiling, page included, because the person choosing it is holding the phone that will ring. A channel made with an API token starts at loud and the token can't raise it. Deciding to be woken up is not something a credential should do on your behalf.
What to put on each one
quiet is for things you want on the record and never want to be told about: a deploy that landed, a backup that finished with the byte count in the body, a certificate that renewed early. You read these when you go looking.
normal is for something a person should see today, on their own time: a payment that failed and will retry, a webhook that gave up, a signup flagged for review. Most channels never need to be louder.
loud is for something that turns into a page if it's left alone: storage down to two replicas of three, a queue growing for an hour, a disk at 92%. It gets through a Focus once and stops.
page is for when somebody has to act and it can't wait until they next pick up the phone: the database is unreachable, the backup hasn't checked in for 25 hours, a probe says the site is down from six cities. It assumes somebody will be found, so use it where that's true.
Quiet hours, mute, and pausing pages
Quiet hours are a window on the channel. Inside it, that channel's messages arrive without a sound. Mute is the same idea in a hurry: an hour of silence from a swipe on either list, from the notification you're looking at, or longer from the channel's own page.
A page ignores both, and there is no setting to change that. A channel that can wake you is a channel you asked to be woken by. If you have a channel that should never wake anyone, the setting you want is its ceiling: hold it at loud and quiet hours hold everything it sends.
There is one thing a page does obey. Pause pages, in the app's settings, runs for half an hour, an hour or two hours. Pages that land inside it go into the feed without a sound, and the moment it closes, the ones nobody answered go out again at full volume. Nothing is dropped. While a pause runs the feed carries a banner counting it down, End now is one tap, and you can move the end. An escalation partner is still paged on time.
A channel can be exempted under During a pause in its own settings. Keep that for the one thing worth standing up and walking out of the meeting for.