# Manage Alerts

> Define up to 10 alerts, optionally limit them with conversation metadata, and see matches in the Inbox and in AI Insights.

Alerts are the conversations you never want to miss. You describe what to watch for in plain language, optionally limit which conversations an alert checks with metadata conditions, and your AI Agent flags the ones that match.

Unlike [Topics](/docs/conversations/insights/manage-topics), which categorize conversations so you can measure volume, alerts exist to catch individual conversations that need attention.

## Create an alert

Go to **Insights → Manage Alerts**. Each alert has four fields:

- **Alert Name** — a short label, up to 100 characters. It is what you will see on the matching conversation, so keep it recognizable: `Refund request`, `Enterprise pricing`.
- **Description**: up to 500 characters. The AI checks this instruction after any metadata conditions pass.
- **Run only when**: optional conditions on conversation metadata, checked before the AI evaluates the description.
- **Active** — switch an alert off to stop matching without deleting it. Paused alerts keep their slot.

You can have **up to 10 alerts** at a time. The remaining count is shown above the list.

## Run only when

Select **Add condition** under **Run only when**. To change the conditions of a saved alert, select its **Edit** (pencil) icon first. Enter a **Metadata key** or choose one from the picker, then select a **Condition**. Enter a **Value** for **equals**, **does not equal**, or **contains text**. For **is one of**, enter each alternative as a separate value chip. Use the raw key, such as `modelName`, without the `metadata_` prefix.

You can add up to **10 conditions per alert**. All conditions must match (AND). An alert with no conditions keeps checking every conversation. Saved conditions are listed under **Run only when**, with AND between them. Conditions use the conversation metadata available when analysis runs.

| Condition | Matches when |
| --- | --- |
| **equals** | The key has a value other than `null` whose text exactly matches **Value**. |
| **does not equal** | The value does not match **Value**, or the key is missing or `null`. |
| **is one of** | The key's text exactly matches any of the listed values. Missing keys, `null`, lists and objects do not match. |
| **contains text** | The key holds text containing the specified text, including capitalization and whitespace. Missing keys, `null` and other value types do not match. |
| **is true** | The key has a value other than `null` that is not false-like. |
| **is false** | The key is missing, `null`, or has a false-like value. |
| **exists** | The key has a value other than `null`, including an empty string, `false`, or `0`. |
| **does not exist** | The key is missing or `null`. |

Metadata keys are case-sensitive. **equals** and **does not equal** compare the whole value as text, including capitalization and whitespace. For **is true** and **is false**, false-like values are `false`, zero, empty strings, empty lists or objects, and the strings `false`, `0`, `no`, `none`, and `null`. These string checks ignore capitalization and surrounding whitespace.

For example, to check for faults with one product, use the description `The visitor reports a fault with the product` and set **Metadata key** to `modelName`, **Condition** to **equals**, and **Value** to `WH-1000XM4C`. The AI evaluates that description only when the stored model name matches exactly. A different model, different capitalization, or a missing model name skips this alert.

To cover several specific models with one alert, select **is one of** and add `K-65XR95M2`, `K-75XR95M2`, and `K-85XR95M2` as separate chips. You can add up to 50 values, each up to 500 characters. Commas remain part of a value. Other condition rows still use AND, so you can also require a particular country. Separate **equals** rows for different values of the same key cannot all match.

Use **contains text** with `XR95M2` when you want every model name containing that text, including additional variants. Matching is literal and case-sensitive, with no wildcards or regular expressions. Empty comparison text is not allowed. Passing these conditions makes the alert eligible; its description must still match the conversation.

## Writing a description the AI can act on

The description is a matching instruction, not a category name. Two things make the difference:

**Describe what the visitor says or asks**, not what you would do about it. `The visitor asks for a refund or disputes a charge` matches reliably; `Billing problems to escalate` does not, because it describes your process rather than the conversation.

**Say what should not trigger it.** Bounding an alert is usually what stops the false positives — for example, `The visitor asks about pricing for more than 50 seats or asks for a custom quote. Not general questions about our published plans.`

Good candidates to start with:

- Refund or chargeback requests
- Enterprise pricing enquiries
- Competitors mentioned by name

## Where matches show up

A matched alert appears in two places:

- **Inbox** — on the conversation itself, in the details pane on the right, as a chip under the conversation analysis.
- **AI Insights** — the **Alerts** filter tab lists every conversation that matched an alert in the selected date range.

Alerts are evaluated as conversations are analyzed, so a new alert applies to conversations from the moment you add it — it does not retroactively re-scan your history.

## Related

- [AI Insights](/docs/conversations/insights/ai-insights) — where matched conversations are collected
- [Manage Topics](/docs/conversations/insights/manage-topics) — categorize conversations instead of flagging them
- [Inbox](/docs/conversations/inbox) — the conversation details pane

---
