Human Handoff

When the AI can't help, conversations are escalated to human agents. The handoff is seamless — the user stays in the same chat, and the agent responds directly from the inbox.

How Escalation Works

The AI triggers escalation automatically when:

1. User explicitly asks — "Let me talk to a human", "speak to an agent"
2. Repeated frustration — After 3+ unsatisfied exchanges
3. Sensitive topics — Billing, refunds, account operations

The chatbot uses the escalateToHuman tool, which:

• Sets the conversation's handoffStatus to "queued"
• Shows a log message in the inbox
• Switches the widget to a "Connecting you to a person…" banner right away

Handoff States

While a conversation is queued or human, the visitor can keep typing: their messages are saved and appear in the inbox, but the AI does not answer. The agent's replies from the Reply tab appear in the widget as messages labelled with the agent's name.

If a visitor sends a message at the very moment a person takes over, the chat endpoint answers 409 with { "handoff": true, ... } instead of an AI stream; the widget handles this silently.

Escalating with automation rules

You don't have to rely on the AI deciding to escalate. In Automation Rules, the Hand over when the visitor asks for a person quick start escalates deterministically on keywords, and assign_agent rules can route escalations (or any conversation) to a specific team member.

Agent Workflow

Taking Over

1. Open the Inbox
2. Look for conversations with an amber "Needs Human" badge
3. Click Take Over in the conversation toolbar. It is also available while the AI is still handling a conversation, to pause the AI and step in
4. The conversation is assigned to you — the widget shows your name

Transferring to a teammate

While a conversation is assigned to you, use Transfer in the toolbar to hand it to another active team member. The transfer is immediate (no acceptance step) and the widget switches to the new person's name.

Responding

Use the Reply tab in the inbox to send messages directly to the user. Use the Private Note tab for internal notes (not visible to the user).

Handing Back to AI

Click Hand Back to AI when the issue is resolved. The user's next message will be handled by the AI again.

Automatic return to the AI

A conversation that sits with a person (queued, or assigned) with no agent activity for a while goes back to the AI by itself, so visitors are never left talking to nobody. Agent activity means replies, private notes and escalation or assignment events; the visitor's own messages don't count.

• The check happens when the visitor next writes: the AI then answers that message and the log shows "handed back to AI by automatic return".
• The default window is 60 minutes. Set HANDOFF_RETURN_AFTER_MINUTES on the rkt-app deployment to change it, or to 0 to turn automatic return off.

Inbox Indicators

• Amber dot in conversation list = queued (waiting for agent)
• Green dot = human agent is handling
• "Needs Human" badge in conversation header
• "Live — Agent Name" badge when assigned

Configuration

Escalation is always available — the AI has the escalateToHuman tool registered as an internal tool that cannot be disabled. The escalation rules are part of the system prompt.