Expertise AI Knowledge Base

   Playbooks  Best Practices & Tips

Best Practices & Tips

Expert tips for writing effective, maintainable playbooks

Last updated on October 27, 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

Ask qualifying or high-value questions early.
❌ Poor order:
1. Ask name
2. Ask email
3. Ask company
4. Ask if they have budget
5. If no budget, disqualify
Wasted visitor's time if they don't have budget.
✓ Better order:
1. Ask if they have budget
2. If no budget, politely exit
3. If yes budget, ask name
4. Ask email
5. Ask company

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