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: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)
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.5. Branching Logic
Branching lets you create different paths based on user responses:Structural Rules
How Steps Work
Sequential by Default: Without branching logic, steps proceed to the next number automatically:When to Add Branching Bullets
Add branching bullets when different options lead to different steps: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
Rule 2: All Options → Same Step = Omit Branches
Examples: Proper vs Improper Branching
Improper (Unnecessary):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