Escalation & Human Handoff

Escalation routes a conversation from AI to a human agent. When the AI determines it needs human help — or a member asks directly — the system notifies the right people, optionally pauses the conversation, and delivers an appropriate message to the member.

This guide covers how to configure escalation behavior, set up notification routing, and customize the member experience.

How Escalation Works

When escalation triggers, the system follows this sequence:

1. Chat flagged — The conversation is marked as needing a human response (needs_response)
2. Chat paused (optional) — The AI stops responding until a human takes over
3. Notifications sent — Priority members and notification rule recipients are alerted via SMS, email, or voice
4. Member message — The member receives an appropriate message based on business hours and configuration

The AI triggers escalation by calling the talk_to_human tool. This happens when:

• The member explicitly asks to speak with a human or real person
• The member expresses frustration with automated responses
• The member indicates their issue is too complex for AI
• The AI determines the situation requires human judgment
• Your workflow prompt instructs the AI to escalate for specific scenarios

Setting Up Escalation

1. Add the Escalation Ability

The Escalation ability provides the talk_to_human tool to your AI. Without it, the AI cannot escalate.

1. Open your workflow (or a specific task within it)
2. Go to the Abilities tab
3. Click Add Ability and select Escalation
4. Configure the settings (see below)
5. Save

Task-level escalation abilities override workflow-level ones, so you can customize escalation behavior per task.

2. Configure Escalation Settings

All message templates are optional. If not set on the ability, the workspace defaults from Workspace Settings are used.

3. Set Up Notification Rules

Notification rules determine who gets alerted when escalation happens and how they're contacted.

1. Go to Workspace Settings → Notification Rules
2. Create a rule with:
   • Notice Type: tool.escalate
   • Member: The team member to notify
   • Workflow (optional): Limit this rule to a specific workflow, or leave blank for workspace-wide
   • Channels: Enable SMS, email, and/or voice notifications

You can create multiple rules to notify different people. The system sends to all matching rules, skipping members who were already notified as priority members.

Workflow-scoped rules take priority — if the escalated chat is on a workflow with specific rules, those fire first, then workspace-wide rules fill in.

4. Configure Business Hours

Business hours determine which message template the member sees (online vs. offline).

1. Go to Workspace Settings
2. Under Escalation, configure:
   • Business Hours: Set available hours for each day of the week
   • Online Message Template: Shown when escalation happens during business hours
   • Offline Message Template: Shown when escalation happens outside business hours
   • Notified Message Template: Shown when agents are successfully notified
   • Paused Message Template: Shown when the chat is paused
   • Pause on Escalate: Default behavior for all workflows (can be overridden per ability)

Guiding the AI to Escalate

The AI decides when to call talk_to_human based on the conversation context and your workflow prompt. You can influence this behavior by adding instructions to your workflow or task prompt.

Prompt-Based Triggers

Add escalation instructions to your workflow prompt to define when the AI should hand off:

If the member mentions self-harm, suicidal thoughts, or indicates they are in
immediate danger, escalate immediately using the talk_to_human tool with
reason "Member safety concern - immediate attention required".

If the member asks a question you cannot answer after two attempts,
escalate with a summary of the question and what you've tried.

If the member explicitly asks to speak with a human, doctor, or supervisor,
escalate immediately.

Assessment-Based Escalation

If your workflow collects assessment data (e.g., PHQ-9 depression screening), you can instruct the AI to escalate based on scores:

After completing the PHQ-9 assessment, calculate the total score.
If the total score is 15 or higher (moderately severe or severe depression),
escalate using talk_to_human with reason "PHQ-9 score [score] -
clinical review recommended".

If question 9 (thoughts of self-harm) is scored 1 or higher,
escalate immediately regardless of total score.

This approach works with any structured assessment — GAD-7 anxiety screening, AUDIT alcohol use, Columbia Suicide Severity Rating Scale, or custom clinical tools your organization uses.

Keyword Awareness

You can instruct the AI to watch for specific keywords or phrases:

If the member uses any of these phrases, escalate immediately:
- "I want to speak to a real person"
- "this is an emergency"
- "I need help now"
- "speak to a manager"
- "I'm going to hurt myself"

Provide the exact phrase used in the escalation reason.

The AI processes these as natural language instructions, so it can handle variations and misspellings — "talk to a real person" matches even if the exact phrase isn't listed.

Routing and Priority

Priority Members

Set Priority Member IDs on the Escalation ability to ensure specific team members are notified first. Priority members receive notifications on all available channels (SMS + email) regardless of notification rule channel settings.

This is useful for:

• On-call staff who should always be the first point of contact
• Clinical leads who need to be aware of all escalations for a specific workflow
• Managers handling VIP or high-risk cases

Notification Rule Routing

After priority members are notified, the system processes notification rules:

1. Rules scoped to the specific workflow are processed first
2. Workspace-wide rules (no workflow specified) fill in next
3. Members already notified as priority members are skipped
4. Each rule specifies its own notification channels (SMS, email, voice)

Combining with Operator Mode

Escalation and Live Operator Mode complement each other:

• Escalation sends notifications to offline team members and pauses the AI
• Operator Mode routes conversations to team members who are actively online

When both are configured, you can handle scenarios where operators are available for immediate handoff during business hours, and escalation notifications reach on-call staff after hours.

Conditional Escalation

Use CEL conditions on the Escalation ability to control when it's available:

cel

cel

cel

See Abilities for more on conditional activation.

API Reference

Notification Rules

Manage escalation routing programmatically via the notification rules API.

Base URL: https://api.gravityrail.com/api/v2/w/{workspace_id}

List Rules

bash

Requires automations:read scope.

Create a Rule

bash

Requires automations:admin scope.

Update a Rule

bash

Requires automations:admin scope. Only include the fields you want to change.

Delete a Rule

bash

Requires automations:admin scope.

Permissions

Tips

• Start with workspace defaults — Configure your message templates and business hours at the workspace level first, then override per-workflow only when needed.
• Always set an offline message — Members who escalate outside business hours should know when to expect a response.
• Use priority members for on-call — Rotate priority member IDs on the Escalation ability to match your on-call schedule.
• Test with chat scenarios — Use Qualifications to test that your escalation triggers fire correctly before going live.
• Combine assessment + escalation — For clinical workflows, pair structured assessments with prompt-based escalation rules so high-risk scores always reach a human.
• Monitor needs_response — Use the Chats list filtered by "needs response" to track escalated conversations waiting for human attention.