Expertise AI Knowledge Base

   Playbooks  Core Concepts & Structure

Core Concepts & Structure

Understanding playbook anatomy, steps, branching, and rules

Last updated on December 30, 2025

Core Concepts & Structure

Playbook Anatomy

Every playbook consists of five key components:

1. Steps (Numbered Instructions)

Steps are the building blocks of your playbook. Each step is numbered and describes what happens at that point in the conversation:
1. @ask_question: "What is your name?"

2. @ask_question: "What is your email address?"
Steps execute sequentially by default unless you add branching logic.

2. Tools (Actions the Agent Takes)

Tools are actions prefixed with @ that tell the agent what to do. Examples:
Multiple tools can be combined in a single step (with some exceptions). See all tools in
Getting Started with Playbooks.

3. Triggers (Activation Conditions)

The trigger defines when your playbook activates:
  • Specific phrase: "I want to book a demo" or "Contact sales"
  • Always active: Leave blank to make the playbook available anytime
  • URL targeting: Use conversation starters to trigger on specific pages

4. Rules (Optional)

Rules let you add specific guidance for how the agent should behave during the playbook. Most playbooks don't need rules—use them only when you need to add context the agent wouldn't otherwise have.
RULES:
- Mention our free trial when relevant

5. Branching Logic

Branching lets you create different paths based on user responses:
1. @ask_question: "What's your company size?" @show_options["1-50", "51-200", "201+"]
    - If the answer is "1-50", proceed to Step 2.
    - If the answer is "51-200", proceed to Step 3.
    - If the answer is "201+", proceed to Step 4.

Structural Rules

How Steps Work

Sequential by Default: Without branching logic, steps proceed to the next number automatically:
1. @ask_question: "What is your name?"

2. @ask_question: "What is your email?"

3. @stop_playbook
One Action at a Time: Each step should focus on a single conversational moment.
Turn-Taking: After each step, the user gets a chance to respond before the next step executes.

When to Add Branching Bullets

Add branching bullets when different options lead to different steps:
1. @ask_question: "Budget allocated?" @show_options["Yes", "No"]
    - If the answer is "Yes", proceed to Step 2.
    - If the answer is "No", proceed to Step 5.
Omit branching bullets when all options proceed to the same next step:
1. @ask_question: "Which area?" @show_options["Billing", "Technical", "Account"]

2. @ask_question: "What is your email?"

The Role of @stop_playbook

Tool: @stop_playbook ends playbook execution and returns the agent to general conversation mode.
Critical: Every path through your playbook must reach @stop_playbook eventually.

Combining Tools

Most tools can be combined in a single step. A few tools like @initialize_live_chat work best on their own step

Language Handling

  • Tool tags: Must always be in English (@ask_question, @show_options, etc.)
  • Playbook content: Can be written in any language
  • Agent responses: Automatically translated to the visitor's detected language

Branching Logic Deep Dive

Rule 1: Different Options → Different Steps = Add Branches

1. @ask_question: "Company size?" @show_options["Small", "Medium", "Large"]
    - If "Small", proceed to Step 2.
    - If "Medium", proceed to Step 3.
    - If "Large", proceed to Step 4.

Rule 2: All Options → Same Step = Omit Branches

1. @ask_question: "Which product?" @show_options["Product A", "Product B", "Product C"]

2. @ask_question: "What is your email?"
All three products lead to Step 2, so no branching bullets are needed.

Examples: Proper vs Improper Branching

Improper (Unnecessary):
2. @ask_question: "Which department?" @show_options["Sales", "Support", "Billing"]
    - If "Sales", proceed to Step 3.
    - If "Support", proceed to Step 3.
    - If "Billing", proceed to Step 3.
Proper:
2. @ask_question: "Which department?" @show_options["Sales", "Support", "Billing"]

3. @ask_question: "What is your email?"

Learn More