Contact Us
Live Support Integration

How Live Support (Human Handoff) Works — Complete Guide

5 minutes Easy 6 steps

Live Support lets your bot gracefully hand off conversations to a human agent when it cannot resolve a user's issue. The entire conversation history is preserved so the agent picks up exactly where the bot left off — no re-introductions, no lost context. You control what triggers an escalation (keywords, AI judgment, or failure count), who can handle escalations (your support staff), and what messages the user sees at every stage of the journey.

What your bot can do after connecting
Keyword Triggers
Auto-escalate when user types specific phrases
  • "speak to a human"
  • "real person please"
  • "I want to talk to support"
  • "escalate this"
  • Any custom phrase you define in configuration
AI-Driven Escalation
Bot escalates when it detects it cannot help
  • Bot outputs <code>ESCALATE</code> directive when stuck
  • Triggered after N consecutive AI failures (configurable)
  • Works alongside normal bot responses
  • Agent sees the exact message that triggered it
Staff Queue
Escalations land in a shared queue staff picks from
  • Pending tab shows all waiting conversations
  • Staff clicks "Accept & Join" to claim a conversation
  • Multiple staff members see the same queue
  • Real-time unread message badge on each ticket
Real-Time Agent Chat
Staff and user exchange messages live
  • Agent types replies in the detail view
  • User sees replies in the chat widget instantly
  • Full conversation history visible to agent
  • Context panel shows trigger reason, user info, what was tried
Resolution & Bot Handback
Close ticket or return to AI bot
  • Mark Resolved → sends configurable resolution message to user
  • Hand back to Bot → AI resumes the conversation
  • Dismiss → closes without messaging user
  • All messages mirrored to chat history for audit trail
Staff Invite System
Invite team members with limited access
  • Staff see only: Live Support queue + their handled chats
  • Invite by email — staff sets their own password
  • Invites expire in 7 days
  • Remove staff access at any time from Staff Management
Before you begin
Active NIVA bot with at least one conversation
At least one staff member to handle escalations (or you as owner)
Live Support enabled in configuration (disabled by default)
Step-by-step setup

Enable Live Support

  • Go to Botmaster → Live Support.
  • Click Configure in the top-right.
  • Toggle Enable Live Support to ON.
  • Click Save Configuration.
Live Support is off by default — no escalations fire until you explicitly enable it.

Set Escalation Triggers

  • In Configuration, find the Escalation Triggers section.
  • Add Trigger Keywords (comma-separated) — e.g. speak to a human, real person, escalate.
  • Optionally set Auto-escalate after N failures — the bot will escalate after that many consecutive unhelpful responses.
  • Leave the failure count blank to rely only on keywords and AI judgment.
Start with 3–5 clear phrases. Too many keywords can cause false triggers.

Customise User-Facing Messages

  • Set the Handoff Message — shown to the user the moment escalation fires (e.g. "Connecting you to a human agent, please hold on…").
  • Set the Away Message — shown when no staff are available.
  • Set the Resolution Message — sent automatically when an agent marks the conversation resolved.

Invite Support Staff

  • Go to Live Support → Staff.
  • Click Invite Staff, enter name and email.
  • Staff receives an email with a unique link to set their password and join.
  • Once accepted, they can log in and access the escalation queue.
Staff accounts have restricted access — they only see the Live Support queue and their own handled chats.

Handling an Escalation (Staff Flow)

  • When a user triggers escalation, a new ticket appears in the Pending tab.
  • Staff clicks the ticket to open the conversation detail.
  • Click Accept & Join — this claims the ticket and notifies the user.
  • Type replies in the reply bar at the bottom. Press Enter or click Send.
  • The user sees replies in real time inside the chat widget.
  • Once resolved, click Resolve — the resolution message is sent and the bot can resume.

(Optional) Configure Working Hours

  • In Configuration, enable Enforce Working Hours.
  • Set start time, end time, and timezone.
  • Outside these hours the Away Message is shown instead of the Handoff Message.
If working hours are not configured, escalations always trigger regardless of time.
Troubleshooting
Escalation does not fire when user types the keyword.
Check that Live Support is enabled in Configuration. Also verify the keyword list is saved — go back to Configuration and confirm the keywords appear. Keyword matching is case-insensitive and checks if the phrase appears anywhere in the message.
User messages during escalation are not visible in the agent chat.
The agent detail page polls for new messages every 2 seconds automatically. If messages are missing, try refreshing the page. Ensure the escalation is in Pending or Claimed status — resolved or dismissed escalations stop buffering new messages.
Agent replies are not appearing in the user's chat widget.
The widget polls /api/escalation-poll/<session_id>/ every 2 seconds when escalated. Check browser console for network errors. Ensure the widget is the NIVA embed and has not been cached — clear widget JS cache or hard refresh the page.
Staff invite email was not received.
Check spam/junk folder. Verify DEFAULT_FROM_EMAIL and email backend are configured in Django settings. You can also copy the invite token link from the Pending Invites table and share it manually.
After resolving, the bot does not resume responding.
Resolving or handing back to the bot clears the is_escalated flag on the session. If the bot still does not respond, confirm the session's active_escalation was cleared — check in Django admin under ChatbotSession for the session ID. A page refresh on the user's widget will also re-sync state.
Staff member cannot log in after accepting invite.
Ensure the invite was not already used (is_accepted = True) or expired. The login page is at /botmaster/login/. Staff use their email address as username. If login still fails, an owner can reset their password via Django admin.
Ready to connect Live Support?
NIVA Botmaster → Live Support → Configure
Open Live Support Queue