Human handoff — live agent takeover

What is human handoff?

Human handoff lets a visitor request a live team member directly from the chat widget. When a handoff is requested:

1. The AI stops responding — it silently saves the visitor's messages so your agent can see them.
2. A Handoff alert appears in Dashboard → Conversations → Handoff tab.
3. An agent claims the conversation, types replies, and the visitor sees them in real time.
4. 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

1. Go to Dashboard → Chatbot → Settings → General.
2. Scroll to the Human Handoff section.
3. Toggle Handoff enabled on.
4. Optionally customise:
   • 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.
5. Click Save settings.

---

How visitors request handoff

Visitors can escalate in two ways:

1 — "Talk to a human" button

When handoff is enabled, a Talk to a human button appears at the bottom of the chat widget. The visitor clicks it at any time.

2 — 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)

---

Claiming and replying as an agent

1. Go to Dashboard → Conversations and click the Handoff tab.
2. You'll see all pending conversations with:
   • Time waiting
   • Trigger type (button or keyword)
   • Claimed / Waiting badge
3. Click a conversation to open it, then click Claim.
4. 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.
5. 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 mobile number.
• When submitted, the number is saved to the conversation's lead capture data — visible in the right panel of the Conversations page.
• A "Continue chatting with AI" 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.