> This page is for Voice AI Platform.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Alerts

> Be told the moment a pattern you care about appears in an agent's calls, instead of finding it later on a dashboard.

An alert watches one agent's calls and notifies you when a pattern you care about appears: a spike
in failed calls, ratings sliding, an integration breaking.

Without alerts, somebody has to open the dashboard and notice. Alerts invert that. The platform
watches continuously and reaches out only when a threshold you set is crossed. Every rule is
re-checked **once a minute**, so a real incident surfaces in minutes rather than whenever someone
next happens to look.

Every alert is five choices.

| Choice             | What you decide                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Which agent**    | Each alert watches exactly one agent                                                              |
| **What to watch**  | One or more conditions, such as *the call was not successful*. With several, **all** must be true |
| **How much**       | A **count** (at least 10 matching calls) or a **percentage** (at least 20% of calls)              |
| **Over what time** | A rolling window of 15 minutes, 1 hour, 6 hours or 24 hours                                       |
| **Who to notify**  | Email and/or webhook, labelled Info, Warning or Critical                                          |

Alerts live inside the agent, in the right-hand configuration panel between **Post-call Analyses**
and **Webhook**.

## When to use one

Alerts are for things somebody needs to act on today. Anything you only review weekly belongs on a
dashboard instead.

**Good reasons to create one**

* **Something might break silently.** A failing integration or a misconfigured number can run for
  hours before anyone notices.
* **A campaign is live.** During an outbound push, a dialer problem costs money by the minute.
* **Quality has a floor.** If a contract promises a standard, an alert tells you before the customer
  does.
* **You just changed something.** After a prompt or tool change, a temporary alert is a safety net.

**Poor reasons**

* **Curiosity.** "How many calls today?" is a dashboard question.
* **Trends.** Slow drift over weeks will not cross a rolling 24-hour window cleanly.
* **Rare events nobody can act on.** If nobody will do anything at 2 a.m., do not page anybody at
  2 a.m.
* **Everything at once.** With only three rules available, each one has to earn its place.

> **Note**
>
> The test before you create one: *if this fires at 3 p.m. on a Tuesday, what does the person receiving
> it actually do in the next hour?* If there is no clear answer, it is a report, not an alert.

## Creating an alert

Open the agent, expand **Alerts**, then **Create Alert**. The whole form is one screen.

![The Create Alert dialog, showing alert name, description, severity, a trigger condition and a count threshold over a time window.](/_fern-img/94e125b8b9dedd3d8bcb090c80aec4b5ed25aa8109b47c28f4440906b8dbb820.webp)

**1. Name it so a stranger understands it.** The name becomes the email subject line. *Failed calls
spike, Riyadh support* is useful at 7 a.m.; *Alert 2* is not. Use the description to tell your team
what to do about it.

**2. Pick a severity.** Severity is a label for the humans reading the alert. It appears in the email
subject and in the webhook payload, and it does **not** change how or where the alert is delivered.

| Severity     | Means                                      |
| ------------ | ------------------------------------------ |
| **Info**     | Worth knowing. Review when convenient      |
| **Warning**  | Something is drifting. Look at it today    |
| **Critical** | Customer impact happening now. Act at once |

**3. Build the condition.** Choose a field, an operator and a value, for example *Call successful ·
Is · False*. Add more conditions to narrow it, remembering they must **all** be true together.

**4. Set the threshold and window.** Switch between **Count** and **Percentage**, then set the number
and the time window. Read back the sentence underneath before saving, it restates your rule in plain
English.

**5. Choose where it goes.** Tick **Email** and enter comma-separated addresses, and/or tick
**Webhook** to post to the agent's configured webhook. At least one channel is required. Slack is
shown as *Soon* and is not available yet.

### Count or percentage

| Use            | When                                                                        | Example                                                      |
| -------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Count**      | Volume is steady, or any occurrence is already too many                     | 10 failed calls in 1 hour                                    |
| **Percentage** | Volume swings a lot, or you care about the share rather than the raw number | 20% of calls rated 2 or lower, minimum 5 calls, over 6 hours |

Percentage mode always carries a minimum call count. Without it, one bad call out of one reads as
100%.

## What you can watch

Eighteen signals from each completed call are available as conditions.

| Group                    | Signals                                           | Typically used for                                  |
| ------------------------ | ------------------------------------------------- | --------------------------------------------------- |
| **Outcome**              | Call successful, call status, end reason          | Failures, outages, calls ending the wrong way       |
| **Customer experience**  | Call rating (0–5), rating comment, user sentiment | Satisfaction dropping, written complaints           |
| **Call shape**           | Duration, message count, function-call count      | Dead-air calls, agents looping or stuck             |
| **Tools & integrations** | Tools invoked, tool status                        | A specific integration failing, or any tool failing |
| **Telephony**            | Call type, from number, to number                 | Inbound versus outbound, one problem number         |
| **Geography**            | Country, city                                     | Region-specific problems                            |
| **Campaign**             | Outbound lead status                              | Contact rates, list quality                         |
| **Content**              | Call summary text                                 | Emerging themes: refunds, cancellations, complaints |

> **Warning**
>
> Only completed calls are counted. A call joins the count when it **ends**, so an alert for calls
> longer than ten minutes fires after those calls finish, not while they are running.

### Alerts you can copy

| Alert                       | Set it to                                      | Catches                                |
| --------------------------- | ---------------------------------------------- | -------------------------------------- |
| **Failed-call spike**       | ≥ 10 unsuccessful calls in 1 hour              | A broken agent or an outage            |
| **High failure rate**       | ≥ 20% unsuccessful, minimum 10 calls, 6 hours  | A quality slide at low volume          |
| **Bad ratings spike**       | ≥ 20% rated ≤ 2, minimum 5 calls, 6 hours      | Satisfaction falling                   |
| **Negative sentiment**      | ≥ 30% negative, minimum 10 calls, 6 hours      | Tone and experience problems           |
| **Outbound not connecting** | ≥ 20 unanswered outbound calls in 15 minutes   | Dialer or number problems mid-campaign |
| **Dead calls**              | ≥ 5 calls under 5 seconds in 1 hour            | Drop-offs and connection faults        |
| **Integration down**        | ≥ 3 calls where a tool errored in 1 hour       | A failing booking or CRM API           |
| **Refund mentions**         | ≥ 10 summaries containing "refund" in 24 hours | Emerging billing issues                |

## What happens when an alert fires

**The firing is recorded.** Every firing stores the exact time window, how many calls matched, and up
to **10 example calls**, so you can go straight to the evidence.

**Notifications go out.** Email arrives from `no-reply@hams.ai` with the subject
`[WARNING] Alert: <your alert name>`. Webhooks receive a signed `alert_triggered` payload at the
agent's endpoint, and failed deliveries are retried automatically.

**The rule goes quiet for a while.** After firing, a rule enters a **cooldown** so one ongoing
problem does not flood your inbox. By default the cooldown equals the alert's own time window, so a
one-hour alert notifies at most once per hour. It resumes watching automatically.

### Why an alert may not fire when you expect

* It is still in **cooldown** from a previous firing.
* The matching calls **had not ended** when the check ran.
* Conditions combine with **and**, so one extra condition can make the rule impossible to match.
* In percentage mode, the **minimum call count** was not reached.
* The alert is switched **off**.

## Limits

| Limit                           | Detail                                                                           |
| ------------------------------- | -------------------------------------------------------------------------------- |
| **3 alerts per workspace**      | The most important constraint. Delete alerts that have stopped earning attention |
| **1 agent per alert**           | Watching the same thing on two agents takes two alerts, and two of your three    |
| **Conditions combine with and** | There is no *or*. To cover two separate situations, use two alerts               |
| **Four time windows**           | 15 minutes, 1 hour, 6 hours, 24 hours                                            |
| **Up to 20 email recipients**   | Prefer a team distribution list over individual names                            |
| **Slack not yet available**     | Shown in the interface as *Soon*. Email and webhook only for now                 |

## Habits that keep alerts useful

1. **Start loose, then tighten.** Set the threshold slightly high and lower it only if you find you
   missed something real. An alert that cries wolf is ignored within a week.
2. **Send to a team, not a person.** People take leave; distribution lists do not.
3. **Put the response in the description.** The person woken by the alert may not be the person who
   created it.
4. **Review monthly.** An alert that never fired is probably set too high. One that fires constantly
   is too low, and everyone has already muted it.

> **Note**
>
> A sensible first three: one **Critical** failure alert, one **Warning** quality alert, and one
> covering whatever is currently live or recently changed. Adjust once you see how often each fires.