---
title: "Trigger conditions"
description: "Decide when your agent should run an action by describing what the visitor is asking for or trying to do."
---

:::note[Plan]
Actions are available on the **Starter** plan and above.
:::

For actions that use trigger conditions, **When to use** describes when the action should run. A widget's **When to show** condition describes when it should appear on its own.

## How it works

For actions with a **When to use** trigger condition, Chatvox checks each new visitor message against that condition:

- **The message matches**: the action runs.
  - If the action needs details the visitor hasn't given yet, such as an order number, the agent asks for them first. The visitor's answer completes the action on their next message.
- **The message doesn't match**: the action doesn't run. The agent knows the action exists but can't use it yet, so it can ask the visitor for what's missing. It never says the action ran.

The details an action needs come from its own settings, such as a Custom API action's [input fields](/docs/actions/custom-api#input-fields). Your **When to use** text only needs to recognize what the visitor wants.

## Set when a widget appears

In your agent, go to **Build** > **Widgets**, open and enable a widget, then select **Settings**. Write its **When to show** condition in plain language, such as "When the visitor wants to book a call or see open times." If the condition matches, the widget can appear without a Custom API action. Leave it empty if an action should be the only thing that shows the widget.

Widgets with a **When to show** condition can appear in the web widget, Public Chat, and Playground. They do not appear on WhatsApp or in REST API conversations. You can also select an enabled widget in a [Custom API action](/docs/actions/custom-api) to show it after that action receives a successful JSON response.

The widget condition works like an action condition: describe the visitor's goal, not the fields the widget needs. Keep it specific enough to distinguish when the widget should and should not appear.

## Focus on what the visitor is trying to do

Write the condition around the visitor's goal. Don't require the details the action needs to collect: if the condition requires an order number or email upfront, a visitor who hasn't given it yet won't match, and the agent won't know to ask for it.

| Too narrow | Better |
| --- | --- |
| "When the visitor asks for order status and gives an order number." | "When the visitor asks where their order is or when it will arrive." |
| "When the visitor gives their phone number and preferred time for a call." | "When the visitor asks for a callback or wants to schedule a call with sales." |
| "When the visitor provides their email address and reason for a return." | "When the visitor wants to return or exchange an item." |

Then make the details required in the action's settings. For example, add **Order number** as a required input field:

> **Visitor**: Where's my order?
>
> **Agent**: I can check that for you. What's your order number?
>
> **Visitor**: A-1234
>
> **Agent**: Order A-1234 has shipped and should arrive on Friday.

## Be specific about the goal

The condition still needs to be clear about which situations it covers:

| Too vague | Better |
| --- | --- |
| "When the user wants help." | "When the visitor asks to speak to a person, or is frustrated after two attempts to solve the problem." |
| "Order questions." | "When the visitor wants to know where their order is, or when it will arrive." |
| "Search the web." | "When the visitor asks about recent news, current prices, or public facts that may have changed." |

## Examples

| Action | When to use |
| --- | --- |
| Check order status | When the visitor wants to know where their order is, or when it will arrive. |
| Check stock | When the visitor wants to know if a product is in stock or available in a size or color. |
| Book a callback | When the visitor wants someone from the team to call them back. |
| Start a return | When the visitor wants to return or exchange an item they bought. |
| Cancel a subscription | When the visitor wants to cancel their subscription. Don't use it when they only ask how cancellation works. |
| Web search | When the visitor asks about recent news, current prices, or public facts that may have changed. Don't search for questions about our own products. |

## Tips

- **Describe the goal, not the required inputs.** The action's own settings handle collecting any missing details.
- **Write in plain, everyday language.** Think of what visitors actually ask for, such as tracking an order, booking a demo, or speaking to someone.
- **Say when not to use it**, if it matters, like the **Cancel a subscription** example above.
- **Keep one goal per action.** If two tasks need different details, create two actions.
- **Join alternatives with "or".** Every part of the condition must be true. "When the visitor asks for a catalog, if they dismissed the form and ask again" never matches a first request, because the visitor hasn't dismissed anything. Write "When the visitor asks for a catalog, or asks for the form again after dismissing it."
- **Test with real messages.** Try messages that should, and shouldn't, trigger the action, including a first message that leaves out the details. The [Playground](/docs/agents/playground) runs actions as your web widget would, and its [action steps](/docs/actions/action-steps) show when a message **almost matched**, so you can see which conditions need rewording. For Custom API, also see [Test it](/docs/actions/custom-api#test-it).
- **Improve a condition.** Select **Improve** to rewrite the current condition more clearly with AI, or **Undo** to switch back. Improving uses a small amount of credit.
- **Try a visitor message.** Enter a message under the condition and select **Try a visitor message** to check whether the action runs or the widget shows. The result says **Runs the action** or **Shows the widget** when it matches. **Almost** means the message is close; make the condition more specific. The check uses a small amount of credit.

:::note
[MCP Server](/docs/actions/mcp-server) works differently: its **When to use** text guides the agent, which decides by itself when to use the server's tools.
:::

## Channels

An action only runs on the channels you've chosen in its **Channels** settings, even if the condition matches.