Human handoff β live agent takeover
Let visitors escalate to a human agent in real time. Agents claim, reply, and resolve from the dashboard while the AI stays silent.
Updated 8 Oct 2026
What is human handoff?
Human handoff lets a visitor request a live team member directly from the chat widget. When a handoff is requested:
- The AI stops responding β it silently saves the visitor's messages so your agent can see them.
- A Handoff alert appears in Dashboard β Conversations β Handoff tab.
- An agent claims the conversation, types replies, and the visitor sees them in real time.
- When resolved, the agent clicks Resolve β the visitor can then start a fresh AI conversation.
Human handoff is available on Starter plan and above.
Enable handoff on a chatbot
- Go to Dashboard β Chatbot β Settings β General.
- Scroll to the Human Handoff section.
- Toggle Handoff enabled on.
- Optionally customise:
- When to offer a person β Only when needed (recommended) or Always show the option (see below).
- Trigger keywords β phrases that prompt the AI to ask if the visitor wants a human (e.g. "speak to someone", "talk to real person").
- Waiting message β shown to the visitor immediately after requesting handoff (e.g. "Connecting you with the team nowβ¦").
- Response timeout β how long (in seconds) to wait for an agent before showing the "team busy" message. Default is 180 seconds (3 minutes).
- Team busy message β shown when no agent claims within the timeout. Includes a mobile-number capture form so you can follow up.
- Click Save settings.
How visitors request handoff
Your AI answers first. Visitors who are offered a person straight away tend to tap it before asking the AI anything, so by default a person is offered only when it's needed.
1 β "Want a person from the team to follow up?"
With Only when needed (recommended), a short suggestion with Yes, ask a person and No thanks appears under the AI's latest answer when:
- the AI couldn't answer (for example strict mode's "I can only answer questions aboutβ¦" reply, or an answer that says it doesn't have that information), or
- the visitor has sent 3 messages in the conversation.
If the visitor taps No thanks, it stays hidden for the rest of the chat unless the AI later can't answer something.
2 β Always show the option
With Always show the option, a Talk to a person button also shows with the quick actions before the visitor's first message, and the suggestion appears under every answer. Tapping either starts the conversation and asks your team to take over straight away.
3 β Keyword detection
If the visitor types one of your configured trigger keywords, the bot will ask: "Would you like to speak with a team member?" with Yes, connect me / No thanks inline buttons.
Handoff states (what the visitor sees)
| State | What the visitor sees |
|---|---|
| Pending | "Waiting for a team memberβ¦" with "Keep this window open"; the header status reads "Connecting you to the teamβ¦" |
| Active | The header status reads "A team member is here"; agent replies appear in real time |
| Team busy (timeout) | Your busy message, a phone number field ("Notify me when available") and a "Continue chatting with AI instead" button; the header status reads "Team busy, leave your number" |
| Resolved | "Conversation resolved β" + "Start new conversation" button |
Claiming and replying as an agent
- Go to Dashboard β Conversations and click the Handoff tab.
- You'll see all pending conversations with:
- Time waiting
- Trigger type (button or keyword)
- Claimed / Waiting badge
- Click a conversation to open it, then click Claim.
- Type in the Reply to visitor box at the bottom. Press Enter or Send β the message appears in the visitor's widget within ~500 ms.
- When you're done, click Resolve. A confirmation dialog appears; click Yes, resolve to close the conversation.
Tip: The sidebar Conversations nav link shows a red badge when unclaimed handoffs are waiting.
What happens when no agent is available
If no agent claims within the configured timeout:
- The widget switches to Team busy state.
- Your configured busy message is shown (e.g. "Our team is currently busyβ¦").
- An inline form prompts the visitor to leave their phone number. It is saved as a contact lead whatever your lead-field settings are. The number must have 6 to 20 digits and may start with + and include spaces, dashes, dots or brackets. The widget confirms only once the number is saved, and offers a retry if sending fails.
- A "Continue chatting with AI instead" button lets the visitor start a fresh AI session immediately.
- Even in the busy state, the SSE connection stays open β if an agent claims the conversation late, the widget automatically upgrades to the Live Agent state without any action from the visitor.
Notifications on new handoff requests
When a visitor requests handoff, Pivra fires a conversation.escalated event. You can connect this to an Action (Dashboard β Actions) to:
- Send an email to your team
- Post a webhook to Slack or your CRM
- Trigger a Zapier or Make workflow
FAQ
Can multiple agents see the same handoff? Yes β anyone on the team can see unclaimed handoffs in the Handoff tab. The first agent to click Claim "owns" the conversation; it's marked as claimed so others know it's covered.
Does the AI respond during handoff?
No. Once a conversation is in handoff status, the AI is silenced. Visitor messages are saved to the thread for the agent to see, but no AI response is generated. After the agent resolves, the visitor can start a new conversation with the AI.
Can I customise which plans have handoff? Handoff is included on Starter, Pro, and Business plans. Free plan users will see a locked state with an upgrade prompt in Settings β General.
What happens to the handoff conversation after it's resolved?
It moves from the Handoff tab to the Open tab with status = closed. The full message thread β including agent replies β is preserved and exportable as CSV or JSON.
Was this helpful?
If you have questions or suggestions, email us at support@pivra.ai .