Create an alert

An alert watches one number, such as your agents' error rate or your credit balance, and tells you when it crosses a line you set, and again when it's back. Alerts are checked every 5 minutes and notify by email, in Slack, at your own webhook, or all three. They're under Observe in the left menu.

Before you start

• Traffic to watch: an agent or a workflow that's in use. Credits left needs nothing.
• For Slack, an incoming webhook URL from a Slack app. For your own system, a public https address that accepts a POST.

Steps

1. 1

   Open Alerts

   Click Alerts under Observe and choose New alert.

2. 2

   Choose what to watch

   Pick the Metric: error rate, errors, p95 latency, requests, thumbs-down rate, average score, credits spent, credits left or workflow failures. See Alert metrics. For Average score, pick the Score key as well.

3. 3

   Choose the scope

   Agent: All agents or one of them (the agent picked in the top bar is preselected). Workflow failures watch All workflows or one workflow. Credits left watches your whole account.

4. 4

   Choose the channels

   Under Channels, tick where the traffic comes from. Widget, Chat link and API are Live and ticked by default; Playground is Test. Live traffic only means a test chat doesn't page anyone.

5. 5

   Set when it fires

   Choose Above or Below and type the threshold. Pick the window under Over the last: 5 minutes to 7 days, 1 hour by default. Rates, p95 latency and scores also have Minimum events (5 by default): with fewer replies, ratings or scores than that in the window, the alert doesn't judge, so 1 error in 2 replies isn't a 50% error rate.

6. 6

   Choose who hears about it

   Email (on by default) goes to your account's email address. Slack takes an incoming webhook URL. Webhook takes a public https address that gets a signed JSON POST. Don't repeat within (1 hour by default) keeps a repeat firing that soon after the last one quiet. See Alert emails, Slack messages and webhooks.

7. 7

   Name it and save

   Alert name is filled in from your choices, such as "Error rate above 5% on Support bot", until you type your own (up to 120 characters). Choose Create alert. If you added a webhook, copy the signing secret it shows now: you won't see it again.

8. 8

   Test it

   On the alert's page, Send test alert sends a real test to every channel you set up, and Check now measures the metric straight away.

How an alert fires and resolves

• Every 5 minutes, each alert that's On is measured over its window. A value equal to the threshold doesn't fire.
• With no data in the window, or fewer events than Minimum events, nothing changes.
• When the value crosses the threshold, the alert goes from OK to Firing, records an event and notifies every channel you set up. While it stays firing, nothing more is sent.
• When the value is back on the right side, the alert goes back to OK and sends a resolved notice to the same places.
• If it fires again within Don't repeat within of the last notified firing, the event is recorded as "Not sent (cooldown)" and nobody is told; its resolve is quiet too.
• Changing the metric, the agent, the workflow or the score key starts the alert again at OK. Changing the threshold, the window or Above/Below doesn't.
• An alert switched Off under Status isn't checked by the schedule. Check now still measures it.

Check now and Send test alert

The alert's history

Each firing, resolve and test is an event. The alert's page lists the last 50 under Events, and the Alerts page shows the latest 20 across all alerts under Recent events, each with what was sent, such as "Email sent, Slack failed" or "Not sent (cooldown)". The Alerts page's Rules list shows each alert's state (OK, Firing or Off), condition, last value and last check.

If something goes wrong