Set up alerts for your team

An alert rule watches one figure of your brand, such as the tickets past their reply target or the invoices that stayed unpaid, and fires when the figure reaches a limit you set. A fired alert is one message for the whole team. It shows in the bell of every member whose role can read it, and it can also go to an email list and to a Discord channel. Members who turn on push notifications get it on their devices too.

The console checks every enabled rule every 5 minutes. The Alerts page, at /staff/alerts (g then x), has two tabs: Notifications, the alerts that fired, and Rules, what makes them fire.

Every member can read the alerts their role can read and mark them read. Setting rules up needs more:

A Read-only member has no Rules tab. A member below billing sees the controls on the Rules tab dimmed, with "Needs billing or higher" beside them.

Each kind of alert also has a lowest role that can read what it announces, the role of the page it comes from. What each alert watches lists it. The bell and the Notifications tab show a member only the alerts of kinds their role can read.

1. Open Alerts and stay on the "Notifications" tab. Its count is your unread alerts.
2. Choose "Unread" to see only the alerts you have not read, or "Everything". The number beside the filter says how many alerts it matches.
3. Read each alert: its severity (Info, Warning or Critical), its title, what it found, how long ago it fired and the rule that fired it. Select the title to open the page that shows the thing, such as the late tickets in the inbox.
4. Choose "Mark read" on an alert, or "Mark all read" for every alert you can read.

The bell in the top bar shows how many alerts you have not read, from the last 30 days: "9+" above nine, and nothing at zero. It opens this page. Marks are your own and nobody else sees them. The page shows 25 alerts at a time, and deletes alerts after 180 days.

An alert whose rule was deleted shows "A rule that was deleted" and stays for Tier 1 support and higher. The bell holds fired alerts only. News about the work, such as a new ticket, is push and the Desk's feed, as Turn on push notifications explains.

1. Open Alerts and choose the "Rules" tab.
2. Under "Add an alert", find the kind you want. Each card says what it watches and which page it reads from (the table below lists them). Choose "Add alert…".
3. Enter a "Name", up to 120 characters. It is how the alert appears in the list and in the bell.
4. Set the numbers of the kind. Each takes a whole number, and the hint under it gives its range.
5. Under "Where it goes", switch on the places:
   • "In the bell" shows the alert in the bell and on the Notifications tab. It is on for a new alert.
   • "Email" sends the alert to the addresses you list under "Recipients". Separate them with commas or put one on each line, up to 20. The alert needs at least one.
   • "Discord" posts the alert to a Discord channel through a webhook. Paste the address under "Webhook address". We never show it again once you save. The rule then shows "Webhook set", and "Replace webhook…" changes it.
6. In "Quiet after firing", enter the least time between two alerts, from 5 to 10,080 minutes. A new alert has 240.
7. Leave "Alert is on" switched on, or switch it off to save the rule paused.
8. Choose "Add alert".

An organization keeps up to 50 alerts. The 51st answers "An organization keeps up to 50 alerts. Delete one to add another."

A Discord webhook address starts with https://discord.com/api/webhooks/. We also accept ptb.discord.com, canary.discord.com and discordapp.com, and refuse every other address so an alert can never be pointed at another server.

Each alert reads the same figure as the page it opens, with that page's own rule, so an alert and its page agree. The numbers of a kind have a range, and the table gives the default first.

The "At least" numbers take 1 to 1,000, except Invoices overdue and Servers that need a look, which take 1 to 10,000. The page reads a rule aloud from these words, such as "Invoices overdue · 5 or more invoices unpaid more than 3 days past due".

Every 5 minutes the console reads the figure of each enabled rule. A rule fires when its figure has reached the limit and its quiet time since the last fire is over. One fire is one alert for the whole team, whatever the number of channels. A figure that stays over the limit fires again each time the quiet time ends, and one that falls under the limit stays quiet until it crosses again.

A rule's row on the Rules tab says how it is doing: "Checked 2m ago · reading 7 · last fired 1h ago", or "Not checked yet" and "never fired" before its first check. The reading is the figure the rule last saw, in the unit of its kind. A paused rule is not checked. Changing a rule's numbers clears its last reading until the next check.

• In the bell: a fire writes one alert for the team, which every member who can read the kind sees with their own read mark. A rule without this channel writes nothing to the bell, and its fires are not in the digest.
• Email: each recipient gets a plain email with the alert's title as its subject, what it found, a link to the page and the rule's name. It leaves through your brand's own mail setup.
• Discord: the webhook posts a card with the title, what it found and a link, in blue for Info, amber for Warning and red for Critical.
• Push: a fire also goes by push to the members who have the Alerts switch on, as Turn on push notifications explains. A test does not.

A test sends the rule's alert to every place it goes, so you can check the email address or the Discord channel without waiting for a fire.

1. On the Rules tab, choose "Test" on the rule's row. Inside the editor, choose "Send a test".
2. Read the toast. "Firing now. Sent: bell, email." says the figure is over the limit and which places took the test. "Not firing now." says it is under the limit. A place that did not take it follows as "Skipped: Discord (No Discord webhook address is saved for this alert.)", with the reason.

A test reads the figure now and sends it whether or not the rule is firing. Its title starts with "Test: " and its text starts with "This is a test of the alert" and the rule's name. It shows in the bell and on the Notifications tab with that title. It leaves the rule's quiet time and last fire alone, goes to no push device and stays out of the digest. Each member can send 10 tests an hour.

• "Edit" opens the same editor with the saved numbers. A rule keeps its kind. To watch another kind, add a new rule.
• "Pause" stops checking and keeps the rule's settings, and "Resume" starts it again.
• "Delete…" asks you to confirm with "Delete alert". The rule stops checking at once. The alerts it already sent stay on the Notifications tab.

A member who gets the daily or weekly email digest reads the alerts that fired in its period under "Alerts that fired": up to the 10 newest, each with its title linked to the page, its severity and the time in your brand's time zone, and what it found. When none fired, the section says "No alerts fired in this period." Only alerts that went to the bell appear, and tests never do. Get an email digest explains how a member chooses one.

Each rule shows "On" and when it was last checked. A fire shows in the bell of every member who can read it, and in the channels you chose, and the rule's row shows "last fired" and the reading that set it off.

The rule says "Not checked yet"

It has not had its first pass, or you changed its numbers. The console checks every 5 minutes.

The rule is over its limit and nothing arrived

The quiet time since its last fire may not be over. The row shows when it last fired. Shorten "Quiet after firing" or wait. A paused rule is not checked, and a rule without "In the bell" writes nothing to the bell.

Add at least one recipient to send this alert by email.

You switched on "Email" with no address. Add one under "Recipients", or switch the channel off.

Add a Discord webhook address to send this alert to Discord.

You switched on "Discord" with no webhook saved. Paste the address, or switch the channel off.

That is not a Discord webhook address. It starts with https://discord.com/api/webhooks/.

The address is not a Discord webhook, or it is on another host. Copy it again from the channel's integration settings in Discord.

Pick at least one place for it to go.

Switch on at least one of "In the bell", "Email" or "Discord".

An organization keeps up to 50 alerts. Delete one to add another.

Delete a rule you no longer need.

429 with rate_limited after a test

You sent 10 tests in the last hour. Wait the number of seconds in Retry-After.

A member cannot see an alert you fired

Their role cannot read that kind. The bell shows each member only the kinds their role can read, as What each alert watches lists.

• The staff console
• Manage the staff team and console settings
• Answer customer conversations
• Handle billing in the staff console

The routes live under https://api.coritan.com/api/v1/orgs/{org_slug}/staff/, and take a console session or a member's access token as The staff console explains. The reference lists them under Staff alerts.

curl https://api.coritan.com/api/v1/orgs/acme/staff/alerts/kinds \
  -H "Authorization: Bearer $STAFF_TOKEN"

The answer is {"kinds": [...]}. Each kind has its kind word, label, description, source (the console page its figure comes from, such as Invoices), min_role (the lowest role that can read what it announces) and params. Each parameter has a key, label, default, min, max, suffix (the unit to show beside it) and phrase, the fragment the console puts the value into when it reads a rule aloud.

curl -X POST https://api.coritan.com/api/v1/orgs/acme/staff/alerts/rules \
  -H "Authorization: Bearer $STAFF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Overdue invoices", "kind": "invoices_overdue", "params": {"min": 5, "days": 3}, "channels": ["in_app", "email"], "recipients": ["billing@example.com"], "cooldown_minutes": 240}'

The answer is the rule:

{
  "id": 7,
  "name": "Overdue invoices",
  "kind": "invoices_overdue",
  "params": {"min": 5, "days": 3},
  "channels": ["in_app", "email"],
  "recipients": ["billing@example.com"],
  "discord_url_set": false,
  "cooldown_minutes": 240,
  "enabled": true,
  "last_checked_at": null,
  "last_fired_at": null,
  "last_value": null,
  "created_by_name": "Alex Example"
}

discord_url_set says whether a webhook address is saved. A rule with email and no recipient, or with discord and no address, answers 422, and the 51st rule answers 409.

PATCH /staff/alerts/rules/{rule_id} takes the same fields, all optional, so send only what changes. Changing the kind resets params to the new kind's defaults unless you send them, and clears the last reading and the last fire. Changing params clears the last reading. A discord_url replaces the saved address, and an empty value removes it. A body that changes nothing answers 400 Nothing to change., and an unknown rule answers 404 Alert not found. DELETE keeps the alerts the rule already raised, and they show to Tier 1 support and higher from then on.

curl -X POST https://api.coritan.com/api/v1/orgs/acme/staff/alerts/rules/7/test \
  -H "Authorization: Bearer $STAFF_TOKEN"

The answer says what happened:

{
  "firing": true,
  "value": 7.0,
  "sent": ["in_app", "email"],
  "skipped": [],
  "message": "Sent a test to the bell and email. The alert is firing now."
}

sent lists the channels that took the test. skipped lists the ones that did not, each as {"channel": "discord", "reason": "..."}. A rule whose kind no longer exists answers 409, and the tenth test of the hour is the last: the next answers 429.

curl "https://api.coritan.com/api/v1/orgs/acme/staff/notifications?unread_only=true&limit=25" \
  -H "Authorization: Bearer $STAFF_TOKEN"

The answer is {"items": [...], "unread": 3, "total": 12}. Unread alerts come first and then the newest. total counts what the filter matches, and unread is the number on the bell: your unread alerts from the last 30 days. Each item has id, title, body, severity (info, warning or critical), href (a console path), created_at, read (your own mark), rule_id and rule_name. You see the alerts of the kinds your role can read.

POST /staff/notifications/read marks alerts read for you. Send {"ids": [41, 42]}, up to 500 of them, or {"all": true}. It answers {"marked": 2, "unread": 1}. An id you cannot read is ignored. A body with neither answers 422, and a call with no member behind it, such as an API key, answers 403.