Human Handoff Node

Documentation for the Human Handoff node in the SMSPort Visual Bot Builder. Learn how to pause the automated bot, transfer conversations to human agents in the SMSPort Inbox, and enforce presence locking.

When an automated chatbot encounters a medical emergency, a frustrated patient, or a complex query that requires clinical judgment, the Human Handoff card immediately transfers the active conversation to live staff in the SMSPort Inbox and locks the bot from interrupting.

Technical Overview & Inbox Mechanism

sequenceDiagram
    autonumber
    actor Customer as Patient
    participant Bot as SMSPort Bot Engine
    participant Inbox as Agent Inbox (/inbox)
    actor Agent as Doctor / Care Coordinator

    Customer->>Bot: "I have severe chest pain and dizziness"
    Bot->>Bot: Evaluates urgency condition
    Bot->>Customer: "Transferring you immediately to emergency triage..."
    Bot->>Inbox: Creates active ticket (Priority: Emergency, BotLocked: true)
    Inbox->>Agent: Emits audio alert & highlights chat in Red
    Agent->>Inbox: Takes presence lock and replies
    Agent->>Customer: "Hello, this is Dr. Verma. Please remain seated..."

Bot Pause (Presence Lock): The bot ceases auto-responses to incoming messages from this phone number until an agent explicitly releases the conversation back to the bot or resolves the ticket.
Realtime Broadcast: The conversation appears instantly at the top of the SMSPort Live Chat queue with SSE / WebSocket notifications for active desk agents.

Inspector Screen: Field-by-Field Guide

When you click on a Human Handoff card in the Visual Builder canvas, the property inspector displays:

1. Handoff Message (`message`)

Label on Screen: Notice to Customer
Required: Yes
What to Fill: The immediate polite message dispatched to the customer informing them an agent is stepping in.
Example: "Connecting you with an on-duty medical coordinator. Please hold on for a moment."

2. Department / Team Queue (`teamId`)

Label on Screen: Routing Department
Options: Doctor Triage | Billing & Invoices | Pharmacy Desk | General Reception
Default: General Reception

3. Priority Level (`priority`)

Label on Screen: Ticket Priority
Options: Low | Normal | Urgent | Emergency
Effect: In the SMSPort Agent Inbox, Emergency tickets flash with a red banner and sound an audible chime.

4. Auto-Apply Tags (`tags[]`)

Label on Screen: Tags to Attach
What to Fill: Comma-separated tags (e.g. urgent_cardio, vip_patient, spanish_speaker) to categorize the lead in the CRM and helpdesk.

5. Bot Lock Duration (`lockMinutes`)

Label on Screen: Lock Duration (Minutes)
Default: 120 (2 hours)
What to Fill: Number of minutes the bot stays muted. If no agent speaks or after the duration expires, the conversation can automatically return to the bot.

Step-by-Step Tutorial: Emergency Clinical Escalation

Here is how to wire an emergency keyword detection flow:

Add Ask Text Node:
- Prompt: "Please describe your primary symptom or reason for contacting us today:"
- Save to: patient_symptom
Add Condition Node:
- Formula: or(contains({{patient_symptom}}, 'chest pain'), contains({{patient_symptom}}, 'breathing'), contains({{patient_symptom}}, 'bleeding'))
Connect Branches:
- true Branch: Connect to Human Handoff Node:
  - Message: "⚠️ This sounds like an urgent clinical situation. We are routing your chat to our emergency duty doctor right now."
  - Priority: Emergency
  - Department: Doctor Triage
  - Tags: urgent_triage
- false Branch: Connect to Ask Button Node for standard appointment booking.

Common Issues & Troubleshooting

1. "Customer replies but bot answers instead of waiting for agent"

Cause: lockBot was set to false or the lock duration expired.
Fix: Ensure the Human Handoff card has Bot Lock toggled ON with an adequate duration (e.g. 120 minutes).

2. "How does the agent return the conversation back to the bot?"

In the SMSPort Inbox: In the top action bar of the chat conversation, the agent can click the Release to Bot button. The bot will resume executing from the canvas trigger on the customer's next message.