# Actions overview

> Actions are the tools your agent can use mid-conversation — call your API, show an interactive widget, capture a lead, search the web, or connect a service like Shopify or Stripe. The agent decides when to use each one.

An **action** is a tool you give your agent. Where the agent's knowledge lets it *answer* questions, actions let it *do* things — look up an order over your API, show an interactive widget, capture a lead, search the web, or call a connected service like Shopify or Stripe. The agent decides when to use each action from its **“when to use”** description, calls it with the inputs it collected from the customer, and uses the result in its reply.

> **WHERE IT LIVES:** Open an agent and go to the **Actions** tab. You'll see your **active actions** at the top and a gallery to **add an action** below. Each action has an on/off switch, an Edit dialog, and a **Test** button so you can run it with sample inputs.

## How an action gets triggered

Every enabled action is handed to the AI model as a function‑calling tool (`actionService.toolDefs`). For each one, the model receives three things:

```js
{ name: a.name,                 // e.g. "go_to_pricing"
  description: a.description,    // your "when to use" text
  parameters: <input schema> }  // the inputs + their descriptions
```

Then, on every turn, the model decides whether to call a tool by weighing all of:

1. **The description** — the biggest lever you control ("when to use").
2. **The action name** — `go_to_pricing` is itself a strong hint; `action_7` wouldn't be.
3. **The parameter descriptions** — e.g. an input "order_id — the customer's order number" tells it when it has what it needs.
4. **The customer's actual message** + the conversation so far.
5. **The agent's system prompt** (general instructions/persona).

So it's not purely the description, and importantly it's not keyword matching — the model makes a semantic judgment. You don't have to list every literal phrase; you describe the intent, and it generalizes (someone saying "what'll this run me?" still matches a pricing description even though they never said "pricing").

### What that means practically

- A vague description like "Show the X widget" gives the model nothing to decide on → it fires unpredictably (or never).
- A good description states the situations/intents that should trigger it. Listing a few example phrasings helps (it anchors the model), but you're giving examples of intent, not an exact-match list.
- Name + inputs reinforce it, so a clear name and well‑described inputs also improve reliability.

## Actions vs. Skills

**Skills** are written playbooks (instructions) injected into the agent's prompt — they teach it *how* to handle a situation, and can call APIs through a generic request tool. **Actions** are structured tools with typed inputs the agent calls directly. They work hand in hand: a skill can describe a workflow and rely on actions (or the built-in request tool) to carry out the steps. See [Skills overview](/docs/skills/overview).

## Types of action

| Type | What it does |
| --- | --- |
| **Custom — Call API** | Calls your own HTTP endpoint and returns the JSON to the agent to use in its answer. |
| **Custom — API + Widget** | Calls your API, then renders the response as an interactive [widget](/docs/widgets/overview) in the chat. |
| **Custom — Widget only** | Shows an interactive widget (a form, card, picker) with no API call. |
| **Custom — Run code (Client)** | Runs your JavaScript in the visitor’s browser, on your site — add to cart, redirect, open a drawer, fire a pixel. |
| **Custom — Send to Help Desk** | Collects the inputs you define and opens a ticket in your [Help Desk](/docs/help-desk/overview) inbox for your team to reply to. |
| **Built-in** | Ready-made tools: Collect leads, Custom form, Suggested messages, Web search, Custom button, Live chat / escalate. |
| **Connector** | Calls a third-party service — Shopify, Stripe, Slack, Cal.com, Calendly, Zendesk, HubSpot, Salesforce, Intercom, and more. |

## Run mode: automatic vs. confirm

Every action runs either **automatically** or **asks the user to confirm first**. Use confirm for anything that changes data — cancelling an order, updating a profile, charging a card — so the customer approves before it happens. Read-only lookups can run automatically.

## Connect a service

Connector actions call a third-party API. Add the connector from the Actions gallery, then set its credentials under **Settings → Integrations** so the agent can authenticate. Without credentials the action returns a clear auth error rather than failing silently.

## Hand off to a human

Add a **Send to Help Desk** action (a [custom action](/docs/actions/custom) type) so the agent can open a ticket in your [Help Desk](/docs/help-desk/overview) when it can't resolve something itself — collecting name, email, and the question, then routing it to your team.

> **NO ESCALATION CONFIGURED? IT SHARES YOUR CONTACT DETAILS:** When **no** Send-to-Help-Desk or escalation action is set up, the agent doesn't dead-end. It falls back to sharing the business's real contact details from its knowledge — your contact page, support email, and hours — so the customer always has a way to reach a person.

## What's next

- [Create a custom action](/docs/actions/custom) — Wire the agent to your own API or a widget.
- [Widget-backed actions](/docs/actions/widgets) — How widgets and actions fit together.
- [Skills](/docs/skills/overview) — Playbooks that work alongside actions.