Alert design is the part of bot-building nobody shows you, because it isn’t code. It’s a series of decisions about whose afternoon gets ruined, and for most of this year the answer was “mine, in new and creative ways”. Here are the rules we ended up with, each one with the mistake that produced it.

Rule 1: bot errors go to one DM

The mistake: an #bot-alerts channel. Everyone joined. Everyone muted it within a week, including me, the person who made it. An unread count of 300 in a channel communicates nothing except “this channel exists”. An unread count of 1 in a DM with a red badge on it makes me look, every time, against my will.

So every bot error, from every bot, lands in my DM. I’m the one who can fix bots, so I’m the one who should be interrupted by them. Nobody else sees raw errors, which is a kindness.

This is what that DM looks like, re-created in a test workspace with invented ids and errors. The first message follows the production code exactly: the attempt count, a link to the chat, and the command to finish it by hand. The second shows the collapse rule from Rule 3 below:

Rule 2: case alerts tag the person who can act

When the claims logger writes a row from a support chat and isn’t sure about something, that’s not a bot error. It’s a case question. It goes to the team channel and tags exactly two people: the agent who handled the chat, and me. The agent can answer “yes, that was a missing item, not a quality claim”. I can fix the rule if the bot keeps asking the same thing like a child in the back seat.

Not @channel. Not @here. Two people with a reason to read it. Everyone else gets to keep doing their job.

New agent on the team? They go on the bot’s tag list on day one, or the bot will keep tagging the person who left in August.

Rule 3: retries don’t alert, give-ups do

A retry loop that alerts on every attempt turns one root cause into a hundred notifications, which is roughly what the 2 October evening looked like. Now retries are silent, the final give-up posts once with a count, and identical errors within 30 minutes collapse to one line.

Rule 4: a photo is shown once

The claims logger attaches the customer’s photo (a crushed box, the wrong item) as evidence when it alerts about a case. The first version attached the same photo every time it mentioned the case. Agents saw the same crushed box three times and stopped looking at photos entirely, which is the opposite of the point.

Now the bot records which photos it has shown. A photo appears once, on the first alert about that case. Later alerts reference it in words.

Rule 5: words mean what the tool means

The bot used to say “on hold” for any chat that was still open. Agents read “on hold” as “we’re waiting on the customer”. Those are different states and the difference matters at 5pm. Now “on hold” appears only when the support tool reports the chat as snoozed. An open chat is “in progress”. Matching the bot’s vocabulary to the tool’s removed a whole category of confusion that I had, technically, invented.

Rule 6: the same customer re-sending isn’t a new alarm

Customers re-send the same message when they don’t get a reply within a few minutes, which is fair. The bot used to flag the second message as a possible duplicate claim. Now, within 24 hours and while the first chat is still open or on hold, a re-send is the same case and doesn’t alert. (It’s rule 12 of the logger’s twenty, where the other nineteen live.)

What this looks like in practice

My DM gets a few bot errors a week. The team channel gets a handful of case questions a day, each with a name on it. Nobody is muting anything. That’s the entire measure of success for alerting: are people still reading it a month later. Everything else is a dashboard.

One line from me

Every rule here started as a notification someone muted. Send fewer, to the one person who can act, and they’ll keep reading.

The bot that reads those DMs first is in the error watcher post.

More on this topic: the Slack bots & approvals guide, with every post in reading order.