Expertise AI Knowledge Base

   Playbooks  Best Practices & Tips

Best Practices & Tips

Expert tips for writing effective, maintainable playbooks

Last updated on December 30, 2025

Best Practices & Tips

Writing Effective Playbooks

Keep Steps Minimal

Ideal: 5-7 steps
Maximum: 10 steps (only if absolutely necessary)
Why:
  • Shorter playbooks are easier to maintain
  • Less likely to have errors
  • Better completion rates
  • Each step should have a clear purpose

Ask One Thing at a Time

Focus each step on a single conversational moment.
❌ Wrong:
1. @ask_question: "What is your name and email address?"
✓ Better:
1. @ask_question: "What is your name?"

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

Use Clear, Conversational Language

Write as you would speak.
❌ Avoid:
@ask_question: "Please provide your electronic mail address for correspondence purposes."
✓ Prefer:
@ask_question: "What's your email?"

Front-Load Important Questions

Put your most important questions early in the flow. If a visitor drops off mid-playbook, you'll still have captured the key information.
1. @ask_question: "What is your name?"

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

3. @ask_question: "What company are you with?"

4. Additional qualifying questions...

Branching Tips

Only Branch When Necessary

Add branching bullets ONLY when different options lead to different steps.
❌ Unnecessary branching:
1. @ask_question: "Department?" @show_options["Sales", "Support", "Billing"]
    - If "Sales", proceed to Step 2.
    - If "Support", proceed to Step 2.
    - If "Billing", proceed to Step 2.
✓ No branching needed:
1. @ask_question: "Department?" @show_options["Sales", "Support", "Billing"]

2. @ask_question: "What's your email?"

Ensure All Paths Exit

Every branch must eventually reach @stop_playbook.
❌ Dead-end path:
1. @ask_question: "Interested?" @show_options["Yes", "No"]
    - If "Yes", proceed to Step 2.
    # Missing path for "No"!

2. @ask_question: "Email?"

3. @stop_playbook
✓ All paths complete:
1. @ask_question: "Interested?" @show_options["Yes", "No"]
    - If "Yes", proceed to Step 2.
    - If "No", proceed to Step 4.

2. @ask_question: "Email?"

3. @stop_playbook

4. @mention_specifically: "No problem!" @stop_playbook

Tool Usage Tips

Prefer @ask_question Over Forms

Conversational question steps feel more natural than forms.
Benefits of @ask_question:
  • Higher completion rates
  • Feels like conversation, not interrogation
  • Easier to add personality
  • Better mobile experience
Use @show_contact_form only when:
  • You need to collect many fields at once (5+)
  • Form is gated content requirement

Never Mention CRM Brand Names

Use generic terms.
❌ Wrong:
"I'm creating a HubSpot ticket..."
"I'll add you to Salesforce..."
✓ Correct:
"I'm creating a support ticket..."
"I'll add you to our CRM..."

Testing and Validation

Save Early and Often

Save button validates structure automatically.
What it checks:
  • Step numbering
  • Branch references
  • Tool syntax
  • Path to @stop_playbook

Test in Demo Mode

Use the chat demo to test end-to-end:
  1. Click "Preview" or "Test"
  1. Trigger the playbook
  1. Try different paths through branches
  1. Verify all tools work correctly
What to verify:
  • Questions display correctly
  • Options appear as buttons
  • Branching works (different paths)
  • Forms/microsites trigger
  • Tickets created (check CRM)
  • Live chat handoff works
  • Playbook ends properly
 

Related Pages