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:

Tool: @ask_question: Ask for information

Tool: @show_options: Display multiple-choice buttons

Tool: @mention_specifically: Output exact verbatim text

Tool: @recommend: Retrieve relevant information from training materials

Tool: Creating Support Tickets: Create a ticket in HubSpot or Salesforce

Tool: @initialize_live_chat: Hand off to a human agent

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 Domain Guidance)

The RULES section provides domain-specific guidance to the agent during playbook execution:


RULES:
- Mention our 30-day free trial when speaking to SMBs
- Emphasize 24/7 support availability for Enterprise customers

Important: RULES are optional and should be minimal (0-3 rules). They appear AFTER all steps including @stop_playbook.

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.

Combination Constraints

Must Be Alone:

Tool: @initialize_live_chat — Must be in its own step with no other tools

Can Combine Freely:

All other tools can be combined as needed

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

Getting Started with Playbooks - Overview and all tools

Complete Playbook Examples - See these concepts in action

Best Practices & Tips - Expert guidance on structure

Quick Reference - Syntax and patterns cheat sheet

Expertise AI Knowledge Base

Core Concepts & Structure