> ## 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.

# Procedures: step-by-step workflows for your AI agent

> Give your AI agent a multi-step Procedure (workflow) end to end to follow whenever a conversation matches a trigger you define.

A **Procedure** captures how your AI agent should handle a specific situation as a repeatable, standard operating procedure (SOP). Each one pairs a **trigger** (the situation that engages it) with an ordered list of **steps** the AI agent works through, including the [Actions](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md) it calls along the way. Reach for Procedures on high-stakes flows like refunds, escalations, and onboarding, where you don't want the AI agent improvising.

Procedures run in your AI agent's conversations on every channel where the Actions they reference are available, such as the Chat Bubble, WhatsApp, or email. You build them in **Build > Procedures**.

## When to use a Procedure

| Use | When |
| - | - |
| **Instructions** | The rule applies to every conversation, such as tone, scope, or topics to avoid. |
| **An Action on its own** | The AI agent needs to do one thing, such as look up an order, and it's fine for the AI agent to decide when. |
| **A Procedure** | The situation needs several steps in a set order, a check before acting, or a different path depending on the answer. |

Reach for a Procedure when the order of steps matters (look up the order before offering a refund), when there are eligibility rules (orders older than 30 days go to your team), or when an Action is sensitive. For sensitive Actions, also turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures) so the Action can only run after the Procedure's checks pass. If a single rule covers the case, such as "Share our returns page link when customers ask about returns," keep it in your [instructions](https://chatbase.co/docs/user-guides/chatbot/build.md).

![Image](https://mintcdn.com/chatbase/E_y2kiaZWNVgFExv/images/image-2.png?fit=max\&auto=format\&n=E_y2kiaZWNVgFExv\&q=85\&s=9ae8ca601eecee5664c65395542f2a1c)

## Anatomy of a Procedure

Every Procedure has three parts:

| Field | Purpose |
| - | - |
| **Name** | A human-readable label (e.g. "Refund Request"). Shown on the conversations and used in [analytics](#analytics). |
| **Trigger** | A description of *when* this Procedure should engage: the situation or intent that should route the conversation here. Labeled **When to use** in the editor. |
| **Steps** | The ordered list the AI agent follows. Steps can reference Actions and branch on conditions. |

![Image](https://mintcdn.com/chatbase/E_y2kiaZWNVgFExv/images/image-5.png?fit=max\&auto=format\&n=E_y2kiaZWNVgFExv\&q=85\&s=0931ac58febc939d5019293fe66e075c)

## Steps

Steps run **in order**, top to bottom. There are two kinds:

* **Instruction steps**: a plain instruction the AI agent follows ("Ask the customer for their order number").
* **Branch steps**: a decision point with one or more **If** / **Else if** conditions and an optional **Else**. To add one, choose **Condition** from the `@` menu. The AI agent evaluates the conditions top-to-bottom, runs the **first** matching branch, then continues after the branch.

> [!NOTE]
>
> Limits: up to **15** instruction steps per Procedure, up to **5** branches per decision point (`if` / `else if` / `else`), and a branch **can't** be nested inside another branch.

### Referencing Actions with `@`

Inside a step, type `@` to reference an [Action](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md) the AI agent should run at that point (for example `@lookup_order`). When the AI agent reaches that step, it invokes the tool.

![Referencing an Action in a step with @](https://mintcdn.com/chatbase/NJfShid4JZYXGQTj/user-guides/chatbot/images/procedures/procedure-action-mention.png?fit=max\&auto=format\&n=NJfShid4JZYXGQTj\&q=85\&s=a0585aaa13337888024cda5d282a9170)

> [!WARNING]
>
> If a step references an Action that isn't available on the current channel, the **entire Procedure is skipped** for that conversation. See [How Procedures run](https://chatbase.co/docs/user-guides/chatbot/procedures/how-procedures-run.md#procedures-are-dropped-when-an-action-isn-t-available).

> [!NOTE]
>
> If a step references an Action that doesn't exist or is disabled, the editor flags it and won't let you enable the Procedure until you fix or remove the reference.

### Using variables with `{{ }}`

You can personalize your steps and branch conditions with `{{token}}` variables that are resolved at runtime. Type `{{` in a step or condition to open the picker, which groups the available variables into:

| Group | Variables | What it resolves to |
| - | - | - |
| **Contact attributes** | `{{contact.name}}`, `{{contact.email}}`, `{{contact.phonenumber}}` | The matched contact's saved details. |
| **Custom attributes** | `{{contact.custom_attributes.*}}` | Any custom contact attributes you've defined for this AI agent. |
| **Session attributes** | `{{user.name}}`, `{{user.email}}` | Identity passed by the embedding site for the current session. |
| **Helpdesk** | `{{agentAvailable}}` | `true` when at least one human agent on your Helpdesk team is available right now (handy in branch conditions). |

> [!NOTE]
>
> A variable resolves only when its value is available for the conversation. For example, `{{user.email}}` is empty unless the embedding site passes it, and `{{contact.*}}` requires a matched contact. Write steps so the AI agent can still proceed (or asks for the value) when a variable is missing.

![Inserting a variable token in a step](https://mintcdn.com/chatbase/IkfpPnVHYRsS79t8/user-guides/chatbot/images/procedures/procedure-variable-mention.png?fit=max\&auto=format\&n=IkfpPnVHYRsS79t8\&q=85\&s=bf332c7ea277a29b56a0e0c90e479079)

## Start from a template

Don't want to build from scratch? Open the **Templates** tab to browse ready-made Procedures for common flows like order returns, subscription cancellations, and billing disputes, all grouped by category. Pick one to create an editable copy, then tailor its trigger and steps to your business.

## Creating a Procedure

**1. Open the Procedures tab**

Go to your AI agent and then click on **Build** from the side bar, then open **Procedures**, then click **Add Procedure** (or start from a [template](#start-from-a-template)).

**2. Name it and define the trigger**

Give it a clear name, then use the **When to use** field to describe the trigger: the situation that should route the conversation to this Procedure.

**3. Add steps**

Add instruction steps, reference Actions with `@`, add variables with `{{ }}`, and add conditional branches where the flow forks.

**4. Enable it**

Save and set the Procedure to **Active**. Only active Procedures are considered at runtime.

> [!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).

## Examples

The examples below show the step syntax in practice. The Action names are examples: type `@` in a step to pick the Actions on your own AI agent.

### Refund request

This Procedure uses [Shopify Actions](https://chatbase.co/docs/user-guides/chatbot/actions/shopify-actions.md) to check an order before refunding it, and sends older orders to your team with [Escalations](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md).

**When to use:** The customer wants to return an item or get a refund for a past order.

**Steps:**

```text theme={null}
1. Use @Get_Orders to find the order the customer wants a refund for.
2. If the order was delivered more than 30 days ago:
     Tell the customer the order is outside the return window.
     Use @create_ticket so the team can review the request, then stop.
3. Ask which items the customer wants to return, and confirm them.
4. Use @Create_Return to open the return on the order.
5. Confirm the return is open. Use the customer's name ({{contact.name}}) if it's available.
```

Step 2 is a branch step with a single **If** and no **Else**, so a recent order skips it and moves on to step 3. To make sure the return only happens through this flow, turn on **Only use in Procedures** on the `Create_Return` Action.

### Damaged or missing item

This Procedure collects the details of an order issue, then hands the customer to a person in real time if someone is available, or opens a ticket if not. It uses [Chatbase live chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) and Escalations.

**When to use:** The customer says an item in their order arrived damaged, is missing, or is the wrong item.

**Steps:**

```text theme={null}
1. Use @Get_Orders to find the order the customer is asking about.
2. Ask which item is affected and what is wrong with it.
3. If the item is damaged:
     Ask the customer for a photo of the damage.
4. If {{agentAvailable}} is true:
     Use @live_chat to hand the conversation to a teammate now.
   Else:
     Use @create_ticket with the order number and a description of the issue.
     Tell the customer the team will follow up on their ticket.
```

`{{agentAvailable}}` is `true` when at least one human Helpdesk agent is available, so this Procedure only offers live chat when someone can answer. Because Chatbase checks every Action a Procedure references, including those inside branches, the Procedure is skipped on any channel where `Get_Orders`, live chat, or Escalations is off. See [How Procedures run](https://chatbase.co/docs/user-guides/chatbot/procedures/how-procedures-run.md#procedures-are-dropped-when-an-action-isn-t-available).

## Analytics

Open a Procedure and switch to the **Analytics** tab to see how it's performing over a date range you choose:

| Metric | Meaning |
| - | - |
| **Triggered** | How many times the AI agent engaged this Procedure. |
| **Pending** | Runs still in progress: the flow was triggered but hasn't finished yet. |
| **Resolved** | Runs that reached their end. |

A trend chart below the counters breaks the same numbers down by day, so you can spot patterns (for example, a spike in refund requests) at a glance.

![Procedure analytics tab](https://mintcdn.com/chatbase/IkfpPnVHYRsS79t8/user-guides/chatbot/images/procedures/procedure-analytics.png?fit=max\&auto=format\&n=IkfpPnVHYRsS79t8\&q=85\&s=bc13baf62876d4b34e7a92ea1f4dbb0f)

## Frequently asked questions

> [accordion] How many steps can a Procedure have?
>
> A Procedure can have up to 15 instruction steps. Each branch step can have up to 5 branches (**If**, **Else if**, and **Else**), and a branch can't be nested inside another branch.

> [accordion] Can two Procedures run at the same time?
>
> No. The AI agent runs at most one Procedure per turn, the one whose trigger best matches what the customer is asking for right now. It can switch to a different Procedure on a later turn if the customer changes topics. To handle two things together, combine them into one Procedure with branches. See [How Procedures run](https://chatbase.co/docs/user-guides/chatbot/procedures/how-procedures-run.md).

> [accordion] Does a Procedure need to use Actions?
>
> No. A step can be a plain instruction, such as "Ask the customer for their order number." Reference Actions with `@` only where the AI agent needs to look something up or make a change.

> [accordion] Why does my Procedure work on my website but not on WhatsApp?
>
> A Procedure is skipped on any channel where one of its referenced Actions is disabled or not supported, even if that Action is inside a branch that never runs. Turn on every referenced Action for that channel in the Action's **Channels** section.

> [accordion] How do I see whether a Procedure is working?
>
> Open the Procedure's [Analytics](#analytics) tab to see how many runs were triggered, pending, and resolved. In [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md), filter conversations by **Procedure used** or **Procedure result** to read the conversations themselves.

## Next steps

> [card] [How Procedures run](https://chatbase.co/docs/user-guides/chatbot/procedures/how-procedures-run.md)
>
> Understand triggering, one-Procedure-per-turn, and how Procedures interact with Actions.


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