Skip to main content
Human Handoff lets a visitor move from your AI chatbot to a real team member without leaving the chat widget. The AI can also trigger a handoff on its own when it can’t answer a question or the situation calls for human judgment.

​
Enabling Human Handoff

Go to Dashboard > Settings and toggle Human handoff (“Allow visitors to request a human agent from the widget”). It’s off by default. When enabled, two things change:
  • The widget shows a Talk to a person button next to the message composer.
  • The AI is given a transfer_to_human tool it can call on its own — the AI is instructed to send the visitor a brief message first, then hand off, whenever the visitor explicitly asks for a human, the AI can’t answer the question, or the situation needs human judgment (complaints, billing disputes, etc.).
When Human handoff is off, the AI instead gets a collect_contact_info tool: it triggers your contact capture form so the visitor can leave their details for a follow-up, since there’s no live agent to transfer to.

​
How Visitors Request a Human

There are two paths into a handoff:
  1. Manual — the visitor clicks Talk to a person in the widget.
  2. AI-initiated — the AI calls transfer_to_human with a reason (user_requested, cannot_answer, or complex_issue) and a short summary for the agent.
Either way, the conversation is escalated and the widget switches into a waiting state while it looks for an available agent.

​
What Visitors See

The widget shows a status banner that changes as the handoff progresses: The visitor can keep typing while waiting — a note reminds them “Your messages will be seen by the next available agent.” If they cancel, the AI resumes immediately. If no agent claims the conversation within a minute, the widget offers a leave-a-message form. Submitting it sends the visitor’s email and message and confirms with “Message sent. We’ll reply by email.” This is separate from Offline Mode, which only applies when your AI provider itself is unavailable. Once an agent claims the conversation, the banner switches to “[agent name] is here to help.” When the agent releases the conversation, the widget shows “You’re now chatting with AI again” and the banner clears itself a few seconds later.

​
Business Hours Interaction

If you’ve configured a business hours schedule, the widget only offers Human handoff during those hours — the humanHandoffEnabled flag sent to the widget is true only when the workspace setting is on and the current time falls within your configured schedule. Outside business hours, the widget falls back to the AI-only experience (or your configured offline behavior) even if Human handoff is enabled in settings.

​
How Agents Take Over (Inbox)

Escalated conversations appear in the Inbox with an Escalation Context card at the top of the thread showing:
  • The visitor’s name and email, if known
  • How long they’ve been waiting
  • Why the conversation was escalated (“Visitor requested human agent” or “AI detected need for human help”)
  • An AI-generated summary of the conversation for context, when one is available
An unclaimed escalation shows a Claim & Reply button. Any conversation can also be claimed from the chat panel header:
  • Claim pauses AI responses and assigns the conversation to you.
  • Release hands it back — AI responses resume.
You can also assign a conversation to a specific teammate, or use auto-assign, from the agent picker in the chat panel header.

​
AI-Resume Behavior

While an agent is assigned, the AI does not respond — only the human agent’s replies reach the visitor. When the agent releases the conversation (or unassigns), the widget shows a system message that the agent has left, briefly displays “You’re now chatting with AI again,” and the AI resumes handling the conversation.

​
Escalation Effects on the Conversation

Escalating a conversation:
  • Sets its status to reflect it needs attention and marks the resolution as escalated to a human
  • Records an escalatedAt timestamp and, when available, the escalation reason
  • Generates a short AI summary of the recent transcript in the background (2-3 sentences covering what the visitor wants, what the AI already tried, and what they likely need next) if the AI didn’t already provide one when it called transfer_to_human
A conversation can only be escalated once — if it’s already been escalated, a repeat request is a no-op. The escalation timestamp is preserved even after the conversation is later closed, so escalation counts stay accurate in Conversations and your analytics reporting.

​
Tips

  • Review the escalation reason before replying. “AI detected need for human help” usually means the AI hit a real knowledge gap — worth checking whether your knowledge base needs an update.
  • Claim quickly. The widget only waits 60 seconds before offering the visitor a leave-a-message fallback, so an idle Inbox means missed live conversations.
  • Release when you’re done, don’t just navigate away — releasing is what tells the AI to resume responding to the visitor.