> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agent Actions: let your agent take action for customers

> Actions let your AI agent do more than answer questions: trigger a task, pull in data, or hand off to a person

Actions are tools your Chatbase AI agent can use during a conversation to trigger a task, pull in data, or hand off to a person, so it can resolve requests instead of only replying to them. Each Action connects your AI agent to a specific tool or workflow, such as a Shopify order lookup, a Calendly booking, a support ticket, or your own API. You choose which channels each Action works on, from the Chat Bubble on your website to WhatsApp, Instagram, email, and phone.

You add and configure Actions in **Build > Actions**. The AI agent decides when to call each Action based on the **When to use** instructions you write for it.

> [!NOTE]
>
> You can create more than one Action of the same type. For example, Escalations on your website and Escalations on Instagram, in case they need separate **When to use** rules or different data to collect from the customer before opening the ticket.

> [!NOTE]
>
> Saving puts your changes in a draft. Your customers see them once you click **Publish** in the top-right corner. A few settings go live as soon as you save. See [Drafts and versions](https://chatbase.co/docs/user-guides/chatbot/versions.md#settings-that-go-live-right-away).

## Available Actions

### Support and handoff

| Action | What it does |
| - | - |
| [Escalations](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md) | Create a support ticket in your ticketing system when a customer needs human help |
| [Chatbase live chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) | Hand off from the AI agent to a human agent in Chatbase |
| [Salesforce live chat](https://chatbase.co/docs/user-guides/chatbot/actions/salesforce-actions.md) | Hand off to a human agent in Salesforce |
| [Freshchat live chat](https://chatbase.co/docs/user-guides/chatbot/actions/freshchat-live-chat.md) | Hand off to a human agent in Freshchat |
| [Sunshine live chat](https://chatbase.co/docs/user-guides/integrations/sunshine.md) | Hand off to a human agent in Sunshine |
| [Transfer to phone number](https://chatbase.co/docs/user-guides/chatbot/actions/transfer-to-phone.md) | Forward a live voice call to a human on a phone number |

### Commerce

| Action | What it does |
| - | - |
| [Shopify](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md) | Recommend products, manage the cart, place orders, handle returns and exchanges, and answer order and delivery questions |
| [Stripe](https://chatbase.co/docs/user-guides/chatbot/actions/stripe-action.md) | Handle billing, invoices, and subscription queries in chat |
| [WhatsApp Catalog](https://chatbase.co/docs/user-guides/chatbot/actions/whatsapp-catalog.md) | Setup guide: show your Shopify products as native WhatsApp product cards instead of plain text |

### Lead capture

| Action | What it does |
| - | - |
| [Collect leads](https://chatbase.co/docs/user-guides/chatbot/actions/collect-leads.md) | Capture customer details as leads |
| [Collect data](https://chatbase.co/docs/user-guides/chatbot/actions/collect-data.md) | Conversationally collect any custom fields you define, mid-chat |
| [Custom form](https://chatbase.co/docs/developer-guides/website-integration/client-side-custom-forms.md) | Collect information from customers with a custom form |

### Scheduling

| Action | What it does |
| - | - |
| [Cal.com](https://chatbase.co/docs/user-guides/chatbot/actions/cal.md) | Let customers check availability and book meetings without leaving the chat |
| [Calendly](https://chatbase.co/docs/user-guides/chatbot/actions/calendly.md) | Let customers check availability in the chat, then finish booking on Calendly |

### Other

| Action | What it does |
| - | - |
| [Custom Actions](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md) | Call your API, run client-side code, and optionally show an interactive Widget |
| [Suggested messages](https://chatbase.co/docs/user-guides/chatbot/actions/suggested-messages.md) | Show suggested replies based on the conversation |
| [Slack](https://chatbase.co/docs/user-guides/chatbot/actions/slack.md) | Post a notification to a Slack channel you name |
| [Web search](https://chatbase.co/docs/user-guides/chatbot/actions/web-search.md) | Give your AI agent real-time web search to answer questions with live data |
| [Custom button](https://chatbase.co/docs/user-guides/chatbot/actions/custom-button.md) | Add buttons that trigger your own links and redirects |

![Available AI Actions](https://mintcdn.com/chatbase/7b2M0UKqzeDuDyGO/images/Actions.png?fit=max\&auto=format\&n=7b2M0UKqzeDuDyGO\&q=85\&s=c7993a69808aea4ec74d1e0df32349cb)

## How the AI agent decides to call an Action

An enabled Action is a tool the AI agent can use, not a script it must run. The AI agent can call an Action only when all of these are true:

1. **The Action is enabled** on your AI agent.
2. **The Action is turned on for the current channel.** See [Channels](#channels).
3. **The request matches the Action's When to use instructions,** or a Procedure step references the Action with `@action_name`.

If [**Only use in Procedures**](#only-use-in-procedures) is on, the Action runs only from a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) step, never on the AI agent's own judgment.

### Write clear When to use instructions

The **When to use** field tells the AI agent when an Action applies, and a vague one is a common reason an Action never fires or fires at the wrong time. A descriptive **Action name**, such as `create_ticket_refunds`, also helps the AI agent understand what the Action is for.

Describe the situation in the phrases customers actually type, and say when not to use the Action if another Action could match the same request. For example, a **When to use** for a Shopify order lookup could read:

```text theme={null}
Use this tool when the customer asks where their order is, when it will arrive,
or what the status of a specific order is. Do not use it for product questions
or for starting a return.
```

## Example: a customer asks where their order is

This example uses the [Shopify](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md) **Retrieve and display orders** Action (named `Get_Orders` by default), enabled for the Chat Bubble.

**1. The customer asks a question**

A shopper on your store opens the Chat Bubble and types "Where is my order?"

**2. The AI agent picks the Action**

The AI agent checks which Actions are available on the Chat Bubble. The request matches the **When to use** of `Get_Orders`, so the AI agent calls it.

**3. The AI agent identifies the order**

If the shopper is signed in to your Shopify store, their orders are retrieved directly from their account. A guest is asked to verify the order with their checkout email and order number, or their phone number and order number. If [Search by confirmation number](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md#search-by-confirmation-number) is on, the confirmation number works in place of the order number. See [Signed-in and guest customers](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md#signed-in-and-guest-customers).

**4. The AI agent replies from the result**

The Action pulls the order status directly from Shopify, and the AI agent writes its reply from it. A shipped order appears as **Shipped**, or **On its way** once the carrier reports it in transit.

This reply costs twice the model's usual credits, because the AI agent used the model once to call the Action and once to write the reply. See [Credit usage](#credit-usage).

## Channels

Every Action has a **Channels** section in its configuration that controls where the Action is available. Channels appear in one of three states:

| State | What it means | What you can do |
| - | - | - |
| **Configured** | The channel is set up on your AI agent and the Action works there. | Toggle the Action on or off for that channel. |
| **Unconfigured** | The Action works on this channel, but you haven't set the channel up yet. | Click on the 'Setup' button to configure it. |
| **Incompatible** | The Action can't run on this channel at all. | Nothing. The channel is listed but can't be selected. |

Configured and unconfigured describe your own setup, so the same Action shows a different split on different AI agents. Incompatible is a property of the Action itself: those channels never become selectable, no matter how you set the channel up.

> [!NOTE]
>
> Enabling an Action on a channel doesn't force it to run there. It only makes the Action available, and the AI agent still decides when to call it based on your **When to use** instructions.

> [!TIP]
>
> See [Channels](https://chatbase.co/docs/user-guides/chatbot/channels.md) for what each channel is and how to set it up.

## Only use in Procedures

Every Action has an **Only use in Procedures** setting in its configuration. Turn it on when you want the Action to run **only** as a step inside a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md), never on the AI agent's own initiative.

When enabled, the Action stays fully functional, but the AI agent won't call it based on its own judgment; it fires only when a Procedure step references it with `@action_name`. Because the AI agent no longer decides when to use it, its **When to use** field is hidden.

Use it for high-control or sensitive tools (refunds, cancellations, escalations) that should fire only at the right point in a defined flow. See [How Procedures run](https://chatbase.co/docs/user-guides/chatbot/procedures/how-procedures-run.md#procedure-only-actions) for how this behaves at runtime.

![The Only use in Procedures setting on an Action](https://mintcdn.com/chatbase/xTz1Dr4Jy6VOvIwv/user-guides/chatbot/images/actions/procedure-only-toggle.png?fit=max\&auto=format\&n=xTz1Dr4Jy6VOvIwv\&q=85\&s=cb435ac71b020c2551bb996cf4eafb5d)

## Actions vs. Procedures vs. instructions

| | What it controls | Use it for | Where |
| - | - | - | - |
| **Instructions** | How the AI agent behaves in every conversation: tone, scope, and rules | "Always answer in a friendly tone," "Only discuss our products" | [Build > Instructions](https://chatbase.co/docs/user-guides/chatbot/build.md) |
| **Actions** | A single thing the AI agent can do, such as look up an order or create a ticket | Any task that needs data or a change in another system | **Build > Actions** |
| **Procedures** | An ordered set of steps for one situation, which can call Actions along the way | Multi-step or high-stakes flows like refunds, where the order of steps matters | [Build > Procedures](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) |

For example, a Shopify return can run as a single Action the AI agent calls when a customer asks. If you want the AI agent to look up the order and ask for a photo before the return goes through, put those steps in a Procedure and turn on **Only use in Procedures** on the return Action. See [Keeping high-stakes Actions on rails](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md#keeping-high-stakes-actions-on-rails) for a full example.

## Credit usage

Actions use message credits based on your AI agent's model. When the AI agent triggers an Action, it uses the model twice: once to run the Action, and once to write the reply from the result. So a reply that triggers an Action costs twice the model's usual credits.

| Model cost | Reply without an Action | Reply that triggers an Action |
| - | - | - |
| 1 credit per message | 1 credit | 2 credits |
| 2 credits per message | 2 credits | 4 credits |

See [Models comparison](https://chatbase.co/docs/user-guides/chatbot/models-comparison.md) for how many credits each model uses.

## Frequently asked questions

> [accordion] Why isn't my AI agent using an Action?
>
> Check that the Action is enabled, turned on for the customer's channel, and has a **When to use** that matches how customers phrase the request. If **Only use in Procedures** is on, an active Procedure must reference it with `@action_name`. Some Actions have their own requirements: several [Shopify Actions](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md#signed-in-and-guest-customers) work only for signed-in customers.

> [accordion] Can an Action fail?
>
> It can, but an Action that's set up correctly shouldn't fail in normal use. When an Action fails, the AI agent writes its own reply based on the error, so the wording depends on the Action and the error. An Action that depends on another system can return an error, for example a [Custom Action](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md) whose response is larger than 20KB. Some Actions let you set what happens next: if a [phone transfer](https://chatbase.co/docs/user-guides/chatbot/actions/transfer-to-phone.md) can't be completed, the AI agent says your failure message and keeps helping the caller. To review Action outcomes, filter [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md) by **Action result**.

> [accordion] How many Actions can my AI agent have?
>
> It depends on your plan. See the [pricing page](https://www.chatbase.co/pricing) for the Action limit on each plan.

> [accordion] Do Actions use extra message credits?
>
> Yes. A reply that triggers an Action uses the model twice, once to run the Action and once to write the reply, so it costs twice the model's usual credits. See [Credit usage](#credit-usage).

> [accordion] How do I test an Action?
>
> Saving an Action puts it in your draft, and the [Playground](https://chatbase.co/docs/user-guides/chatbot/playground.md) always uses your draft. Send a message that should trigger the Action and check the reply. When it works, [publish](https://chatbase.co/docs/user-guides/chatbot/versions.md) it and run [Tests](https://chatbase.co/docs/user-guides/chatbot/tests.md) with **expected Actions** to check that the AI agent calls the right Action. Tests run against your published AI agent, not your draft.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.