> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
# Alerts
> Create Ringg AI alerts that watch a call, tool or Advanced Analysis metric for your workspace or chosen agents, and notify you by email, Slack or webhook.
An alert watches one metric, such as the share of calls customers hang up on, and notifies you when it crosses a threshold, so you hear about a spike without watching [Analytics](/documentation/monitor/analytics).
In the dashboard: **Sidebar โ Monitor โ Alerts**.
## Before you start
An email address, a webhook URL, or a connected Slack channel.
Optional: only to alert on a field your agent extracts.
## Workspace and agent alerts
The page has two tabs, each with a count:
| Tab | Shows |
| - | - |
| **Workspace** | Alerts that watch every agent in the workspace, then the **Recommended** starter alerts you have not turned on yet |
| **Agents** | Alerts limited to chosen agents, grouped under each agent's name. An alert for several agents appears under each one. |
Some metrics only make sense at one level. Tool failure alerts work only per agent ("Tool failure alerts aren't available here โ they only work per agent."). A credit balance alert works only for the workspace.
## Recommended starter alerts
Two starter alerts are listed under **Recommended** ("Starter alerts for common call-quality issues."):
| Alert | Fires when | Window |
| - | - | - |
| **Disconnection rate spike** | Disconnection rate is above 25% | Last 30 minutes |
| **Customer hangup spike** | Customer hangup rate is above 25% | Last 30 minutes |
**Enable** turns one on as is, checked every 15 minutes, with no email, Slack or webhook targets ("Alert enabled"). Nobody is notified until you edit it and add a target. To set the threshold, window and recipients first, click the pencil icon instead.
## Create an alert
Click **Create alert**. The dialog reads "Choose what to watch and where to send the notification."
Enter an **Alert name**, for example "Payment failure rate spike". Under **Scope**, choose **Workspace** ("Monitors every agent in this workspace.") or **Agent** ("Monitors only the agents you select."). For **Agent**, pick one or more agents in **Agents**. Don't have one yet? [Create an agent](/documentation/build-agents/agents/create-an-agent).
Build the sentence under **Trigger**: **Check every** *interval* **for the last** *window*, **when** *metric* *condition* *threshold*. For example: check every 5 min for the last 30 min, when customer hangup rate is above 25%.
Click **Add filter** to count only some calls, such as `outbound` calls or calls on one carrier.
Under **Notify via**, expand **Email**, **Slack** or **Webhook** and add a target ([Notification channels](#notification-channels)), then click **Save**.
You see "Alert created", and the alert is on.
## The parts of a rule
| Part | Options | Default |
| - | - | - |
| **Check every** | 5 min, 10 min, 15 min, 30 min, 1 hour | 5 min |
| **for the last** (window) | 15 min, 30 min, 1 hour, 6 hours, 24 hours | 30 min |
| Metric | Ringg's metric catalog, plus the selected agents' Advanced Analysis fields | None |
| Condition | **is above**, **is below**, **equals** | **is above** |
| Threshold | A number. Rate metrics take a percentage (enter `25` for 25%). | Metric's suggested value, if any |
The metric list comes from Ringg and shows a description under each metric. A balance is read at check time, so it has no window and no filters.
| Metrics | Scope |
| - | - |
| Number of Calls, Connection rate, Disconnection rate (webcall), Customer hangup rate, Avg call duration, Goal completion rate, Negative sentiment share, Positive sentiment share, Response latency p50 and p95, Avg user turns | Workspace or agent |
| Tool failure rate, Tool failure count | Agent only |
| Advanced Analysis fields ([below](#alert-on-an-advanced-analysis-field)) | Agent only |
| Available credits ([Billing](/documentation/manage-account/billing)) | Workspace only |
### Alert on an Advanced Analysis field
When agents are selected, their [Advanced Analysis](/documentation/build-agents/customize-agent-behaviour/advanced-analysis) fields appear in the metric list, marked **Custom analysis** or **Custom analysis ยท numeric**. After you pick one, a second dropdown sets how it is measured:
| Field type | Measure options | Also asks for |
| - | - | - |
| Boolean | **percentage**, **count** | Nothing: counts calls where the field is true |
| Enum or text | **percentage**, **count** | **where** *field* **is** a value |
| Number | **average**, **total** | Nothing |
For example: when **percentage** of `payment_promised` is below 40.
### Filters
Each filter narrows the calls the metric counts. You can add each field once, and only the fields the chosen metric supports are offered.
| Filter | Values |
| - | - |
| **Call type** | `inbound`, `outbound`, `webcall` |
| **Status** | `registered`, `ongoing`, `retry`, `error`, `completed`, `failed`, `cancelled`, `forwarded` ([call statuses](/documentation/monitor/logs#call-statuses)) |
| **Calling source** | The carrier or transport that placed the call, such as `plivo`, `exotel`, `twilio`, `ozonetel`, `whatsapp`, `livekit` (see [telephony providers](/documentation/inventory/phone-numbers/your-own-telephony/byot-overview)). You can also type a value. |
| **Tool name** | A [tool](/documentation/build-agents/customize-agent-behaviour/tools/overview) of the agent (tool metrics). With exactly one agent selected you pick from its tools; otherwise you type the name. |
## Notification channels
The **Create alert** and edit forms need at least one target ("Add at least one notification target.").
| Channel | How to add |
| - | - |
| **Email** | Type an address and click **Add**. Add as many as you need. |
| **Slack** | Pick channels in **Slack channels**. Connect Slack on the [**Tools**](/documentation/build-agents/customize-agent-behaviour/tools/workspace-tools#workspace-tools) page first ("Connect Slack from the Tools page to send alerts to a Slack channel."). |
| **Webhook** | Enter a URL (`http://` or `https://`) and click **Add**. Ringg sends a `POST` with a JSON body. |
### Webhook test, headers and payload
* **Test** sends a test request to the URL in the field. You see "Webhook test delivered" or "Webhook test failed" with the error.
* Open **Advanced webhook settings** to add **Custom headers (optional)**, such as `Authorization`. Add headers before clicking **Add** for the URL. Header values are stored encrypted and are never shown again. When you edit an alert, leave the header rows empty to keep the saved headers.
Under **Advanced webhook settings**, the dashboard shows this sample as the "JSON body Ringg sends on each alert":
```json theme={null}
{
"type": "alert.fired",
"workspace_id": "...",
"rule": { "name": "...", "metric_id": "...", "threshold": 0.25, "condition_type": "gt" },
"event": { "metric_value": 0.31, "sample_size": 142 },
"message": { "title": "...", "summary": "..." }
}
```
`alert.fired`, `alert.still_firing` or `alert.resolved` ([when each is sent](#when-notifications-are-sent)); `alert.test` for a **Test** send.
When the notification was sent.
The workspace the alert belongs to.
The alert that fired.
The alert's ID.The **Alert name**.The watched metric.The alert's severity.The threshold; a fraction for rate metrics (`0.25` is 25%).`gt` (is above), `lt` (is below) or `eq` (equals).The window, in minutes.The selected agents; `null` for a workspace alert.The alert's filters.
What the check measured.
The ID of this firing.The measured value; a fraction for rate metrics.How many calls the value was computed from.
Human-readable text.
Short title.One-line summary.
### When notifications are sent
* **Fired**: once, when a check first crosses the threshold.
* **Still firing**: again on every check while the condition holds, with no cooldown. A Recommended alert that stays above its threshold notifies every 15 minutes.
* **Resolved**: once, when a check finds the condition no longer holds. A window with no qualifying calls can't be measured, so it neither fires nor resolves.
Every target gets each notification. A webhook attempt waits up to 20 seconds. A `429`, a `5xx` or a network error is retried, for 3 attempts in all, a few seconds apart; any status below `400` counts as delivered. A notification that still fails is not sent again.
## Manage alerts
* **Turn off or on:** use the switch on the alert's row. The row also shows the condition (for example `Customer hangup rate > 25%`), the scope and the channels.
* **Edit:** click the pencil icon. The dialog reads "Update the condition, filters, and who gets notified." Scope can't be changed after creation; change the **Agents** list instead. You see "Alert updated".
* **Delete:** open the alert, click **Delete**, then **Confirm delete** (or **Keep**). You see "Alert deleted".
## With the API
Alerts have no public API endpoints; manage them in the dashboard.
## Troubleshooting
Tool failure alerts are agent-only. Set **Scope** to **Agent** and pick at least one agent.
Fields appear only after you select agents, and only fields those agents define in [Advanced Analysis](/documentation/build-agents/customize-agent-behaviour/advanced-analysis).
Connect Slack on the [**Tools**](/documentation/build-agents/customize-agent-behaviour/tools/workspace-tools#workspace-tools) page, then reopen the alert.
Check that the URL is reachable from the internet, accepts `POST` with a JSON body, and that any required auth header is set under **Advanced webhook settings**.
## Next steps
Fix the instructions behind the metric that fired.
Ship the fix and watch the alert go quiet.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
## Create an alert