# Procedures: step-by-step playbooks for your agent

> Write procedures your agent follows step by step for one kind of request, such as a refund: ask questions, call your API actions, check conditions and ask the visitor to confirm before anything changes.

A procedure tells your agent exactly how to handle one kind of request. For a refund, for example: ask for the order number, look the order up with one of your [API actions](/en/docs/api-actions), check whether it can be refunded, and then either refund it after the visitor confirms or explain why not. The agent starts the procedure when a visitor's request matches it and then follows your steps in order, one at a time.

Together with **Only inside procedures** on an action, a procedure also controls when a risky action can run at all: only on the step you put it in, and, if you want, only after the visitor has confirmed.

> Procedures are part of the Starter, Pro and Enterprise plans. See [Plans](#plans).

## Plans

| | Free | Starter | Pro | Enterprise |
| --- | --- | --- | --- | --- |
| Procedures per agent | None | 3 | 10 | No plan limit (up to 50 per agent) |

The agent follows only the first enabled procedures up to your plan's limit, in the order of the list. A procedure past that point shows **Over your plan's limit** in the list. Disabled procedures don't take a place.

On the Free plan the **Procedures** section shows **Included from Starter**. After a downgrade nothing is deleted: procedures you can no longer use stay in the list and work again after an upgrade. A chat that was in the middle of one ends it at the visitor's next message.

## Create a procedure

1. On the **Actions** tab, go to **Procedures** below your actions and click **Add procedure**.
2. Choose **Start from scratch**, or start from a template: **Refund request**, **Cancel a subscription** or **Reschedule an appointment**. A template's action steps have no action yet; pick one of yours in each before you save.
3. Fill in the procedure:
   - **Name**: up to 80 characters. It appears in the list, in **Why this answer** and on the **Conversations** tab. The agent reads it too.
   - **When to use**: up to 500 characters. Read by the agent, not shown to visitors. See [Writing a good "When to use"](#writing-a-good-when-to-use).
   - **Steps**: up to 15. Click **Add step** and choose a type. Use the arrows to change the order and the trash button to remove a step. See [Step types](#step-types).
   - **Agent can follow this procedure**: on by default.
4. Click **Add procedure**.

If something is missing or doesn't fit, the field says what to fix, for example "Pick the action this step calls" or "Pick a step that exists".

In the list, each procedure shows a **Procedure** badge, its number of steps and its **When to use**.

- The **Enabled** switch stops the agent from starting the procedure, without deleting it.
- The arrows change the order. When your plan's limit leaves some procedures out, the ones at the top are followed.
- **Edit** opens the procedure.
- The trash button deletes it. Conversations keep showing that it ran.

Team members with the **Viewer** role see the list and can open a procedure with **View**, but can't change anything.

## Writing a good "When to use"

The agent starts a procedure only when the visitor's request clearly matches its **When to use**. When the match is unclear, it asks what the visitor needs instead.

- Describe the request in the visitor's terms: "The visitor asks for their money back for an order they placed."
- Say what it isn't for when that could be confused: "Not for general questions about the refund policy."
- Keep one kind of request per procedure, and don't let two procedures cover the same request.

A vague text such as "Refunds" makes the agent start the procedure for any question that mentions refunds, including "How long do refunds take?".

## Step types

| Step | What the agent does | Limits |
| --- | --- | --- |
| **Instruction** | What you write, such as explaining a policy, or offering a [hand-off](/en/docs/handoff), a [chat form](/en/docs/chat-forms) or [booking](/en/docs/booking). | Up to 1,000 characters |
| **Ask the visitor** | Asks your question and saves the answer under a name. | Question up to 500 characters |
| **Call an action** | Calls one of your server-side API actions. Optionally asks the visitor to confirm first. | One action per step |
| **Condition** | Checks something you describe and goes to one step if it is true, another if not. | Up to 500 characters |
| **End** | Finishes the procedure, with an optional closing message. | Up to 1,000 characters |

- **Instruction**: the step is done when the agent has done what it says. If it needs the visitor's reply, the agent waits for it. Built-in tools such as the hand-off, forms and booking stay available as usual, so an instruction can tell the agent to use them.
- **Ask the visitor**: under **Save the answer as**, give the answer a name of lowercase letters, numbers and underscores, starting with a letter, up to 32 characters, for example `order_number`. Two steps can't save under the same name. The agent asks in the visitor's language, and if the visitor already gave the answer earlier in the chat, it saves that instead of asking again. An answer can be up to 500 characters. intoCHAT saves only an answer that comes from what the visitor wrote: every number in it must appear in their messages, and most of its words. So the agent can't fill a step with a guess or a placeholder; it has to ask and wait for the reply. It may shorten an answer, but should keep the visitor's own words, in their language.
- **Call an action**: choose one of this agent's server-side [API actions](/en/docs/api-actions). [Client-side actions](/en/docs/client-actions) and [custom buttons](/en/docs/custom-buttons) can't be used. The step is done when the action succeeds, and the agent moves on by itself. When it fails, the step stays where it is: the agent may try once more if the error suggests a fix, or tells the visitor and stops the procedure. See also [Filling action inputs](#filling-action-inputs) and [Visitor confirmation](#visitor-confirmation).
- **Condition**: describe what to check under **If**, for example "The order was delivered less than 30 days ago." Under **If yes, go to** and **If no, go to**, choose **Next step**, **End** or another step. A condition can go back to an earlier step, but not to itself. The agent decides from what the visitor said and what actions returned; when it can't tell, it asks the visitor first.
- **End**: the procedure is finished as soon as the agent reaches this step, and the agent closes it with your message, in its own words. Without a message, it tells the visitor briefly what was done. Going past the last step also finishes the procedure.

## Filling action inputs

In an action step, **Fill inputs from the visitor's answers** sends some of the action's [data inputs](/en/docs/api-actions) exactly as the visitor gave them. Click **Fill an input**, choose the input, and write its value with the names of earlier answers in double braces, for example `{{order_number}}`. A value can also mix fixed text and answers, such as `Order {{order_number}}`, up to 500 characters.

- intoCHAT fills these inputs itself, and they replace whatever the AI would have passed. The agent can't change them.
- Inputs you don't fill are filled by the agent from the conversation, as usual.
- When you save, intoCHAT checks that the action is one of this agent's server-side actions, that each input you fill is one of its data inputs, and that every `{{name}}` is saved by an **Ask the visitor** step before this step.
- If a condition skipped the step that saves an answer, the action isn't called with an empty value. The agent tells the visitor it can't finish and stops the procedure.

## Procedure-only actions

In the editor of a server-side [API action](/en/docs/api-actions), switch on **Only inside procedures** for actions that change something, such as a refund or a cancellation.

- The agent doesn't get the action in a normal chat. It gets it only while a procedure is on a step that calls it.
- A call at any other time is refused with "This action can only run inside a procedure step." and listed as **Failed** in **Why this answer**. Nothing is sent to your API.
- The action shows a **Procedure only** badge in the list. One that no procedure calls is never used.
- Client-side actions and buttons can't be procedure-only.

> Without **Only inside procedures**, the agent can also call the action outside the procedure, like any other action, and the confirmation of a procedure step doesn't apply there. Switch it on for every action that should only run after your steps.

An action that a procedure calls can't be deleted, and can't be changed to a client-side action or a button. The message names the procedures to change first.

## Visitor confirmation

With **Ask the visitor to confirm first** ticked on an action step:

1. The agent's first call doesn't run the action. The agent is told what would be sent, tells the visitor what will happen with those values, and asks them to confirm.
2. intoCHAT runs the action only when the agent calls it again for the same step, with exactly the same values, and the visitor has sent a new message since the agent asked. A call in the same reply as the question is always refused.
3. If the values changed, for example because the visitor corrected the order number, the agent has to ask again with the new values.

The check is done by intoCHAT's server, not by the AI. What the server can't check is whether the visitor's message actually says yes: that is the agent's judgement, and so is every **Condition**. A determined visitor may talk the agent past a condition, so let your API refuse what must never happen, such as refunding an order that isn't eligible or more than its total.

When you fill **every** data input of the action from the visitor's answers (see [Filling action inputs](#filling-action-inputs)), intoCHAT prepares the confirmation as soon as the procedure reaches the step. The agent then shows the values and asks for the yes in that same reply, the action runs at the visitor's next message without asking twice, and it runs with exactly the values the visitor saw, whatever the AI passes. This is the most predictable setup for anything that changes data. When some inputs are left to the agent, it follows the steps above.

When a confirmed call fails, trying again with the same values doesn't ask the visitor again.

## How the agent follows a procedure

- The agent works on one procedure at a time. If the visitor brings up a request for another procedure, it stops the current one before starting the next.
- It stops a procedure when the visitor changes the subject, wants to stop, or the procedure can't continue, and then carries on normally.
- It does one step at a time, in order, and doesn't skip steps or make up the result of an action. In one reply it can do several steps, for example save the order number, look up the order and check a condition.
- What the visitor writes, including their answers, is treated as data. It never changes your steps or their order.

When you change a procedure while a chat is in the middle of it, the chat carries on from its current step after you save. If that step was removed, or you disabled or deleted the procedure, or it is over your plan's limit, the procedure ends at the visitor's next message and the agent carries on normally.

## What you see

- **Why this answer** on the **Conversations** tab lists each step under **Actions called** as "Procedure", with the procedure's name and what happened: **Started**, **Step 2 done**, **Step 3 done (yes)**, **Confirmation asked**, **Completed**, **Stopped**, or **Stopped: procedure changed**. The actions a step called are listed as usual. See [Why this answer](/en/docs/conversations-and-dashboard#why-this-answer).
- In a transcript, the header lists each procedure the chat went through with how far it got, for example "On step 2 of 6 (Ask the visitor)", "Completed" or "Stopped" with the reason. Click it to see the answers the visitor gave.

## Limits

- 15 steps per procedure. Names up to 80 characters, **When to use** up to 500, instructions and closing messages up to 1,000, questions, conditions and input values up to 500.
- Each answer can be up to 500 characters. The agent is shown up to 20 answers of a procedure.
- Procedures per agent depend on your plan, up to 50. See [Plans](#plans).
- Procedures aren't used in temporary chats, because nothing in them is saved.
- In the **Playground**, a saved chat follows procedures like the chat on your site, and **calls your real actions**. Test with a test order or a test endpoint.
- Chats through the [REST API](/en/docs/rest-api) follow procedures too.
- A [duplicated agent](/en/docs/quick-start) gets copies of the procedures, with their action steps pointing to the copy's actions. Which conversations went through them stays with the original.

## Tips

- Keep each step small: one question per **Ask the visitor** step.
- Put a **Condition** right after the lookup it depends on, and describe it in terms of what the action returns.
- End each branch with an **End** step that says what the visitor should hear.
- Switch on **Only inside procedures** and **Ask the visitor to confirm first** for anything that changes data, and fill all of its inputs from the visitor's answers so they confirm exactly what will run.
- Try the procedure in the **Playground**, then open **Why this answer** to see each step.

## Example: a refund request

With a "Look up order" action and a "Refund order" action marked **Only inside procedures**, both with an `orderId` data input:

1. **Ask the visitor**: "What is your order number?" Save the answer as `order_number`.
2. **Call an action**: Look up order. Fill `orderId` with `{{order_number}}`.
3. **Condition**: "The order was found, was delivered less than 30 days ago and hasn't been refunded yet." If yes, go to **Next step**; if no, go to **Step 6**.
4. **Call an action**: Refund order. Fill `orderId` with `{{order_number}}`. Tick **Ask the visitor to confirm first**.
5. **End**: "Tell the visitor the refund has started and that the money arrives within 5 to 10 days."
6. **Instruction**: "Explain why this order can't be refunded, using what the lookup returned, and offer to pass the conversation to the team."

**When to use**: "The visitor asks for their money back for an order they placed. Not for general questions about the refund policy."

A visitor who writes "I want a refund for my order" is asked for the order number. The agent looks the order up, checks it, and tells the visitor it will refund order 1042, asking them to confirm. Only after their reply does the refund run.

## Next steps

- Set up the actions your steps call: [API actions](/en/docs/api-actions).
- Collect several details in one go instead: [Chat forms](/en/docs/chat-forms).
- Pass a chat to your team: [Hand-off by email](/en/docs/handoff).
- See what the agent did: [Conversations and stats](/en/docs/conversations-and-dashboard).