Skip to main content

​
Escalations

Even the best AI can’t solve every customer issue. Escalations ensure customers get human help when needed, seamlessly transferring conversations from AI to your support team. Proper escalation configuration is critical for maintaining customer trust and satisfaction when AI reaches its limits.

​
Why Escalations Matter

Escalations serve as your safety net, ensuring:
  • Customer satisfaction - Users don’t get stuck in frustrating AI loops
  • Issue resolution - Complex or sensitive matters reach qualified humans
  • Trust building - Showing customers there’s always a human available builds confidence
  • Continuous improvement - Escalated conversations reveal where AI needs enhancement
  • Graceful degradation - AI admits limits rather than providing incorrect information
The goal isn’t to minimize all escalations - it’s to escalate at the right time for the right reasons. Some issues should always go to humans.

​
Types of Escalations

botBrains offers two escalation mechanisms with different user experiences:

​
Offer Handoff

User-controlled escalation where the AI drafts an email for the user to review and send. How it works:
  1. AI determines escalation is appropriate
  2. AI composes email with subject and body
  3. User reviews the draft
  4. User can edit the content
  5. User approves and sends, or cancels
When to use:
  • General support questions AI can’t answer
  • Non-urgent escalations
  • When user should control the handoff
  • Situations where user may want to add context
Configuration: Enable in Behavior → Tools → Offer Handoff Example guidance: 
"If you encounter questions about billing disputes, account security issues,
or legal matters, use `offer_handoff` to connect the customer with our
support team. Explain why you're escalating and what the customer can expect."

​
Escalate to Human

Automatic escalation that transfers the conversation immediately without user approval. How it works:
  1. AI determines immediate escalation is needed
  2. Conversation is marked as “escalated”
  3. Support team is notified
  4. User is informed escalation has occurred
When to use:
  • High-priority issues requiring immediate attention
  • Compliance or security concerns
  • Situations where AI should not continue interacting
  • Premium customer tier automatic routing
Configuration: Enable in Behavior → Tools → Escalate to Human Example guidance: 
"For enterprise customers or any conversation involving potential security
incidents, immediately use `escalate_to_human`. Do not continue the
conversation after escalating."
Escalate to Human bypasses user approval. Only use for situations requiring immediate human intervention. For most cases, Offer Handoff provides better user experience.

​
Configuring Email Handoffs

Email handoffs require configuration to function properly.

​
Setting Up Support Email

Navigate to Settings → Handoffs to configure: Project Name
  • Displayed to customers during handoff
  • Included in handoff email subject
  • Should be clear and recognizable
Support Email
  • Email address where handoff messages are sent
  • Must be monitored regularly
  • Can be individual email or team inbox
Example configuration: 
Project Name: Acme Corp Support
Support Email: support@acme.com

​
How Email Handoffs Work

When a user approves a handoff:
  1. Email is sent to configured support_email
  2. Email contains:
    • Subject line (AI-generated or user-edited)
    • Customer’s question/issue
    • Conversation context
    • User’s email address
    • Link to conversation (if integrated)
  3. User receives confirmation that handoff was sent
  4. Conversation is marked with “escalated” status

​
Handoff Email Format

Handoff emails include: Subject: 
[Project Name] Support Request: [AI-generated summary]
Example: [Acme Corp] Support Request: Billing question about annual plan
Body: 
<p>A customer has requested human support through ou AI agent.</p>

<p><strong>Customer Email:</strong> user@example.com</p>

<p><strong>Issue Summary:</strong></p>
<p>[AI-generated explanation of the issue]</p>

<p><strong>Customer's Message:</strong></p>
<p>[User's original question/concern]</p>

<p><strong>Conversation History:</strong></p>
<p>[Link to full conversation if available]</p>
Customers can edit the handoff email before sending, allowing them to add additional context or clarify their issue.

​
Enabling Escalation Tools

Configure escalation tools in your AI’s behavior settings.

​
Step-by-Step Setup

1. Navigate to Behavior Go to Behavior → Guidance in your project 2. Create or Edit Guidance Choose guidance rules where escalation applies 3. Add Tool Instructions Reference escalation tools in instructions: 
"When you encounter questions about [topics you can't handle], use
`offer_handoff` to connect the user with our support team. Draft a clear
email explaining the issue."
4. Enable Tools In Behavior → Tools General, check:
  • Offer Handoff for user-controlled escalation
  • Escalate to Human for automatic escalation
5. Build and Deploy Create new profile version and set as active

​
Tool Configuration Examples

Customer Support Assistant 
Guidance: General Support
Instructions: "Help customers with product questions and account issues.
If you're unable to resolve the issue after 2-3 exchanges, or if the
customer seems frustrated, offer to connect them with our support team
using `offer_handoff`."
Tools: search_docs, offer_handoff
Audience: Everyone
Enterprise Priority Support 
Guidance: Enterprise Escalation
Instructions: "Enterprise customers receive priority support. For any
complex issue, immediately use `escalate_to_human` to ensure rapid response
from our dedicated enterprise support team."
Tools: escalate_to_human
Audience: User.plan = "enterprise"
Security Incidents 
Guidance: Security Issues
Instructions: "If a customer mentions potential security concerns, account
compromise, or suspicious activity, immediately use `escalate_to_human`.
Do not attempt to diagnose or resolve security issues."
Tools: escalate_to_human
Audience: Message contains "hacked", "security", "compromised", "suspicious"

​
When to Escalate

Teach your AI the right escalation triggers.

​
Always Escalate For

Out of Scope
  • Legal advice
  • Medical recommendations
  • Financial guidance
  • Situations requiring professional expertise
Security and Privacy
  • Suspected account compromise
  • Data breach reports
  • Password reset issues (after reasonable attempts)
  • Unauthorized access concerns
High-Value Situations
  • Enterprise customer issues
  • Large order problems
  • Revenue-impacting bugs
  • Contract negotiations
Emotional Escalation
  • User expresses strong frustration
  • Repeated failed attempts to resolve
  • User explicitly requests human help
  • Complaints about service quality
Compliance and Legal
  • Refund requests (depending on policy)
  • Terms of service questions
  • Data deletion requests (GDPR, CCPA)
  • Accessibility accommodations

​
Don’t Escalate For

Simple Questions
  • Information available in knowledge base
  • Common how-to questions
  • Standard product features
First Attempt Issues
  • User hasn’t tried suggested solution yet
  • AI has relevant knowledge to share
  • Issue can be resolved with existing tools
Preference-Based
  • User preference without attempting AI assistance
  • “I want to talk to a human” as first message (try helping first)

​
Gray Areas - Use Judgment

Configure specific guidance for: Billing Questions 
"Answer common billing questions using knowledge base. For billing disputes,
payment failures, or refund requests, offer handoff after explaining our
standard policy."
Technical Troubleshooting 
"Walk users through up to 3 troubleshooting steps. If the issue persists
after following all steps, offer handoff to technical support with a summary
of what was tried."
Product Feedback 
"Acknowledge feature requests and suggestions. For detailed feedback or
feature prioritization discussions, offer handoff to our product team."

​
Integration-Specific Escalations

Escalations work differently depending on your deployment channel.

​
Zendesk Integration

When integrated with Zendesk: Private Mode (Agent Assist)
  • Escalations alert the agent handling the ticket
  • Agent can choose to take over or continue with AI assist
  • Escalation appears as internal note
Public Mode (Public Replies)
  • Escalation creates internal note for agents
  • Ticket status can be updated
  • Triggers can route to specific teams
Configuration: Set up in Integrations → Zendesk → Settings

​
Salesforce Integration

When integrated with Salesforce: Escalations:
  • Update Case status to “Escalated”
  • Assign Case to queue or user
  • Add note to Case history
  • Trigger Salesforce workflow rules
Configuration: Set up in Integrations → Salesforce → Settings

​
Website Widget

For website deployments: Email Handoff Flow:
  1. Widget prompts for user email (if not provided)
  2. User reviews and approves handoff
  3. Email sent to support_email
  4. User sees confirmation message
Customization: Configure messaging in Frames → [Your Frame] → Settings

​
Slack Integration

For Slack deployments: Escalations:
  • Message posted to designated escalation channel
  • Thread context included
  • Support team can respond in thread
  • Original user notified
Configuration: Set up escalation channel in Integrations → Slack → Settings

​
Optimizing Escalation Experience

​
Writing Effective Handoff Messages

When AI generates handoff emails, clarity matters: Good Handoff: 
Subject: Billing Question - Annual Plan Discount

I'm reaching out because I have a question about the annual plan discount
that wasn't fully answered by th AI agent.

I'm currently on the monthly Pro plan ($49/month) and considering upgrading
to annual billing. The AI mentioned a 20% discount, but I'm not seeing this
reflected in my account when I try to change plans.

Could you help me understand:
1. Is the 20% discount automatically applied at checkout?
2. Will I be refunded for the remaining days on my monthly plan?

Thank you!
Poor Handoff: 
Subject: Question

I need help with billing.

​
Guidance for Better Handoffs

Instruct your AI to create helpful handoff messages: 
"When using `offer_handoff`, compose a clear email that includes:
1. Concise subject line summarizing the issue
2. Brief explanation of what the customer needs
3. Relevant context (account details, previous attempts)
4. Specific questions or requests
5. Professional, polite tone

Example subject lines:
- 'API Integration Issue - Authentication Errors'
- 'Feature Request - Export to PDF'
- 'Billing Question - Upgrade Pricing'

​
Setting Escalation Expectations

Prepare users for what happens next: 
"Before offering handoff: 'I'll connect you with our support team who can
help with this. You'll receive a response within 24 hours on business days.
Let me draft an email for you to review.'"

"After handoff sent: 'Your message has been sent to our support team. You
should receive a response at user@example.com within 24 hours. The email
includes all the context from our conversation.'"

​
Monitoring and Improving Escalations

Track escalation patterns to improve your AI.

​
Key Metrics

Escalation Rate
  • Percentage of conversations that escalate
  • Target: 5-15% for most use cases
  • Too high: AI needs better knowledge or guidance
  • Too low: May indicate users giving up instead of escalating
Time to Escalation
  • How many messages before escalation
  • Very quick escalations suggest AI should escalate earlier
  • Long conversations before escalation suggest persistent issues
Escalation Topics
  • Which topics escalate most frequently
  • Reveals knowledge gaps or complex scenarios
  • Guides knowledge base improvements
Resolution After Escalation
  • Were escalated issues resolved?
  • Did escalation lead to satisfaction?
  • Validates escalation was appropriate

​
Analyzing Escalations

Navigate to Analyze → Conversations and filter by: Status: Escalated
  • Review all escalated conversations
  • Look for patterns in questions
  • Identify unnecessary escalations
Tool Usage: offer_handoff or escalate_to_human
  • See when tools were invoked
  • Analyze AI’s reasoning for escalation
  • Verify appropriateness

​
Improving Based on Escalations

Pattern: Same question always escalates
  • Solution: Add knowledge snippet for this question
  • Example: If “How do I export my data?” always escalates, create detailed export guide
Pattern: AI escalates too early
  • Solution: Update guidance to try harder before escalating
  • Example: “Attempt 2-3 troubleshooting steps before offering handoff”
Pattern: AI never escalates when it should
  • Solution: Add explicit escalation triggers to guidance
  • Example: “If user mentions ‘billing dispute’, immediately offer handoff”
Pattern: Escalations for out-of-scope topics
  • Solution: Add knowledge about these topics or make AI decline gracefully
  • Example: “For medical questions, politely explain we cannot provide medical advice and suggest consulting healthcare professional”

​
Best Practices

​
For All Escalations

Be Proactive

Offer escalation before users get frustrated. If AI attempts 2-3 solutions without success, escalate rather than continuing indefinitely.

Explain Why

Always tell users why escalation is happening: “This requires specific account access that I don’t have” or “This is a billing matter best handled by our finance team.”

Set Expectations

Inform users about response times, who will contact them, and what information they’ll need to provide.

Preserve Context

Ensure handoff messages include conversation history so support teams don’t ask users to repeat themselves.

Follow Up

If possible, update users when their escalation has been received and is being processed.

​
For Email Handoffs Specifically

  • Monitor support_email inbox regularly
  • Set up email rules to route handoffs appropriately
  • Track response times to handoff emails
  • Include handoff emails in your support SLAs
  • Consider using shared inbox tools for team visibility

​
For Enterprise Deployments

  • Create VIP escalation paths for high-value customers
  • Use escalate_to_human for enterprise tier
  • Route enterprise escalations to dedicated support staff
  • Implement faster SLAs for enterprise handoffs
  • Track enterprise escalation metrics separately

​
Troubleshooting

​
Handoff Emails Not Received

Check:
  • Support email address is correct in Settings → Handoffs
  • Email isn’t caught by spam filters
  • Email server allows emails from botBrains domain
  • Test with a personal email to verify delivery

​
AI Escalates Too Often

Solutions:
  • Review guidance instructions - may be too cautious
  • Add more knowledge sources to reduce gaps
  • Update tool descriptions to clarify when to use
  • Check audience targeting - wrong guidance may be active

​
AI Never Escalates

Solutions:
  • Verify escalation tools are enabled in Behavior → Tools
  • Check guidance has tools in allowed_tools list
  • Add explicit escalation examples to instructions
  • Test with questions that should trigger escalation

​
Users Decline Handoffs

Investigate:
  • Are users frustrated with AI before handoff offered?
  • Is handoff offer appearing too early?
  • Are users uncertain about response times?
  • Review conversation flow leading to handoff offer

​
Next Steps

Now that you understand escalations: Effective escalations create a safety net that builds user trust. When users know they can always reach a human, they’re more willing to try the AI first.