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

# Structured playbooks

> Numbered steps that run in order, every time.

A structured playbook is a list of steps. The assistant works through them in
order and can't skip one — which is what you want for anything with a compliance,
legal or money consequence.

<Frame caption="A structured playbook: each step has a type and an instruction.">
  <img src="https://mintcdn.com/at-2c802d8e/9XqrvrUSpYjKohuZ/images/26-playbook--damage-claim.png?fit=max&auto=format&n=9XqrvrUSpYjKohuZ&q=85&s=cae0ba249720f450f763cbd01199ca55" alt="A structured playbook in the editor" width="2880" height="1800" data-path="images/26-playbook--damage-claim.png" />
</Frame>

## Step types

<AccordionGroup>
  <Accordion title="Ask — collect something from the caller" icon="circle-question">
    The procedure waits here until it has an answer.

    | Field | What it does |
    | - | - |
    | **Instruction** | What to ask for. |
    | **Collect** | How to hear the answer — the forms callers use, and what to tidy up. |
    | **Save as** | A name for the answer, so later steps can use `{{var.your_name}}`. |
    | **Read it back** | Confirms the value with the caller before moving on. |

    **Collect** is the field that earns its keep. Describe what people actually
    say:

    ```text theme={null}
    Callers describe furniture rather than naming it — "the big wardrobe", "the
    oak one". Match it against the items on the order.
    ```

    ```text theme={null}
    They may read the reference in groups, or with dashes. Strip them.
    ```
  </Accordion>

  <Accordion title="Tell — say something in the assistant's own words" icon="message">
    Give it the point to make and it phrases it, in the caller's language and in
    keeping with the conversation so far.

    Use this for most of what the assistant says.
  </Accordion>

  <Accordion title="Say — speak exact words" icon="quote">
    What you type is what's said, word for word.

    Use it for legal wording and for confirmations that must not be paraphrased.
    Remember it's spoken in the language you wrote it, so a German caller hears
    English if that's what you typed.
  </Accordion>

  <Accordion title="Tool — use one of your tools" icon="wrench">
    Pick the [tool](/tools) and say what it's for. The assistant fills in the
    arguments from the conversation.

    | Field | What it does |
    | - | - |
    | **Tool** | Which one to use. |
    | **Instruction** | What the assistant is trying to achieve with it. |
    | **Retries** | How many times to try again if it fails. Up to 3. |
    | **If it fails** | What to say, and whether to stop the procedure or carry on. |

    To transfer the caller when something fails, set it to stop and make the next
    step a [transfer](/tools/call-transfers).
  </Accordion>

  <Accordion title="If / else — take a different path" icon="code-branch">
    Give each branch a condition in plain language. The first one that matches
    runs, then the procedure rejoins the main list.

    ```text theme={null}
    The damage happened in transit
    ```

    Branches can nest up to three deep.
  </Accordion>

  <Accordion title="Sub-playbook — run another procedure" icon="layer-group">
    Runs another playbook, then carries on from the next step. Good for an
    identity check you need at the start of several procedures.

    Like a tool step, it can retry and has a fallback when the child doesn't
    finish. Playbooks can nest three deep.
  </Accordion>

  <Accordion title="System — end the call or send keypad tones" icon="phone-slash">
    Two actions: end the call, or send DTMF digits (for navigating a menu on
    another system).
  </Accordion>
</AccordionGroup>

## A worked example

Taking a damage claim, from the demo workspace:

| # | Step | What it does |
| - | - | - |
| 1 | **Say** | "I'm sorry that arrived damaged. Damage is handled by a colleague rather than by me, so I won't promise a repair, replacement or refund on this call." |
| 2 | **Tool** | Find the order from the caller's number, or the order number if they give one. |
| 3 | **Ask** | Which item is damaged. *Collect:* callers describe furniture rather than naming it. → `{{var.damaged_item}}` |
| 4 | **Ask** | What the damage is and where. *Collect:* a sentence in their own words is what the damage team needs — don't push for a category. → `{{var.damage_description}}` |
| 5 | **Ask** | When it was delivered, and whether the packaging looked damaged. → `{{var.delivery_and_packaging}}` |
| 6 | **Ask** | Whether they have photographs. *Collect:* yes or no is enough; don't try to collect files. → `{{var.has_photographs}}` |
| 7 | **Tool** | Hand over to support with the item, the description and the photo answer. |
| 8 | **Tell** | Give them the ticket number and when to expect a reply. |

Notice step 1. The expectation is set before anything is collected, so the caller
isn't waiting for an answer the assistant was never going to give.

## Writing good steps

**Set expectations early.** If the procedure can't resolve the caller's problem,
say so in the first step.

**One thing per Ask.** "What's damaged and when did it arrive" gets you half an
answer twice.

**Use Collect, not a format rule.** People say "O R D four four one seven" and "the
fourteenth of March". Describing what you'll hear works; demanding a format gets
you a caller repeating themselves.

**Say for the words that matter, Tell for the rest.** Over-using Say makes the
assistant sound like a recording.

**Keep it short.** If a procedure needs twenty steps, there are probably two
procedures.

## Limits

| | |
| - | - |
| Branch nesting | 3 deep |
| Sub-playbooks | 3 deep |
| Tool retries | Up to 3 |

A playbook has no time limit of its own. The call bounds it — a caller who hangs
up ends it, and one who goes quiet trips the assistant's
[idle timeout](/assistants).


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