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 joins the team's Needs Response queue until a person replies. This is recorded even if nobody can be notified.
2. Chat paused (optional) — The AI stops responding until a human takes over
3. Notifications attempted — Matching priority members, notification-rule recipients, and operator-group members are alerted. Priority members and rule recipients use SMS, email, or voice; operator-group members who are online are notified in the browser instead (see Operator Group Routing). A rule scoped to another workflow, a stale member, or a delivery failure means nobody is paged.
4. Member message — If a teammate was notified, the member receives the business-hours template. If nobody was paged, they see an honest fallback that does not promise a human is coming.

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

Setting	Description
Pause on Escalate	Whether to pause the AI when escalation triggers. If not set, uses the workspace default.
Paused Message	Message shown to the member when the chat is paused.
Notified Message	Message shown when agents have been notified.
Online Message	Message shown during business hours.
Offline Message	Message shown outside business hours.
Priority Member IDs	Team members to notify first, before notification rules are processed.

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)

Operator-group members are resolved last, after rules, and anyone already notified above is skipped.

Operator Group Routing

Select one or more Operator Groups on the Escalation ability to route escalations to a group's members — the same roster Live Operator Mode rings for calls.

• Online members are preferred. If anyone in the group is online, only they are notified, and they receive a browser notification (push notification plus the in-app bell) rather than SMS or email.
• If nobody is online, the whole roster is paged by SMS and email instead, so the escalation still reaches someone.
• The group's own routing strategy applies: Broadcast notifies everyone eligible, Round Robin picks one member per escalation (rotating independently of the call ring, so an escalation doesn't consume an operator's turn on a call).
• Members already notified as priority members or by a notification rule are not notified again.

This is useful when a group of on-call staff keeps Gravity Rail open in a browser and you want them to see an escalation immediately, without paging them by phone.

Combining with Operator Mode

Escalation and Live Operator Mode complement each other:

• Escalation notifies configured recipients, including online operator-group members, and can pause 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:

See the Developer CEL reference for the variables and functions available in this ability context.

# Only enable escalation during business hours
is_business_hours

# Only for members with a specific label
"high-risk" in member.labels

# Only on voice calls
chat.channel == "phone-voice"

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

GET /notification-rules

Requires automations:read scope.

Create a Rule

POST /notification-rules
Content-Type: application/json

{
  "noticeType": "tool.escalate",
  "memberId": 42,
  "workflowId": null,
  "prompt": "Escalate clinical concerns to this member",
  "notifySms": true,
  "notifyEmail": true,
  "notifyVoice": false
}

Requires automations:admin scope.

Field	Type	Description
noticeType	string	Must be "tool.escalate" for escalation rules
memberId	integer	Team member to notify
workflowId	integer or null	Scope to a workflow, or null for workspace-wide
prompt	string or null	Optional description of when to escalate
notifySms	boolean	Send SMS notification
notifyEmail	boolean	Send email notification
notifyVoice	boolean	Send voice call notification

Update a Rule

PUT /notification-rules/{rule_id}
Content-Type: application/json

{
  "notifySms": false,
  "notifyEmail": true
}

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

Delete a Rule

DELETE /notification-rules/{rule_id}

Requires automations:admin scope.

Resolve an Escalation

POST /intervention-requests/{request_id}/resolve
Content-Type: application/json

{}

Requires chats:write scope. The request body must be present (an empty JSON object {}) but carries nothing — it exists so a cross-site form POST cannot reach the endpoint (CSRF barrier).

On success the response is the resolved request (never chat content):

{
  "id": 42,
  "uuid": "0c1e2a3b-4d5e-6789-abcd-ef0123456789",
  "kind": "escalation",
  "chatId": 17,
  "requestingMemberId": null,
  "reasonCode": null,
  "resolution": "handled",
  "resolvedByMemberId": 9,
  "resolvedAt": "2026-09-04T15:14:01Z",
  "createdAt": "2026-09-04T14:02:11Z",
  "notifiedCount": 2
}

resolution is always handled on this route. notifiedCount is how many people were actually told when the escalation opened — zero means it reached nobody. resolvedByMemberId is the operator who closed it.

Resolving closes the escalation for everyone who was notified and hands the chat back:

• the chat's needs response flag clears — unless another attention reason still stands (an unanswered inbound message, another open escalation, a pause something else set, or a chat whose next turn belongs to a person by design), in which case the flag stays up;
• the pause the escalation itself set lifts — under the same condition. A chat paused for any other reason keeps that pause;
• the resolution is recorded as handled on the shared row, and the activity feed carries the escalation.resolved fact.

Response (InterventionRequestResponse):

Field	Type	Description
id	integer	The intervention-request id
uuid	string	Stable public identifier
kind	string	Always escalation on this route (other kinds 409)
chatId	integer or null	Chat the request names
requestingMemberId	integer or null	Who asked, if a person did
reasonCode	string or null	Closed-vocabulary reason, when set
resolution	string	Always handled on this route
resolvedByMemberId	integer or null	Member who resolved it
resolvedAt	datetime	When the row closed
createdAt	datetime	When the escalation opened
notifiedCount	integer	How many people were actually told; 0 means it reached nobody

Errors: 404 if the id does not exist, 403 if the caller cannot see the chat it names, 409 if the escalation was already resolved (the first resolution is authoritative) or if the request is not an escalation.

Permissions

Action	Required Scope
View notification rules	automations:read
Create/edit/delete notification rules	automations:admin
Configure workspace escalation settings	workspace:admin
Configure ability-level escalation	automations:admin
Resolve an escalation (Mark as Resolved)	chats:write

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. A chat stays listed while the escalation is open and no person has replied; resolving it or replying clears it.