Human handoff

The shape of it

Your app owns the people. Bolcho owns the queue. You push a roster of operators and a heartbeat; Bolcho decides who gets the next conversation, measures how long customers waited, returns work when someone disappears, and keeps an audit trail. Your app renders the inbox and calls the actions below.

0 — Turn it on

handoffEnabled on the assistant (PATCH /agents/{id}) is the master switch, and it is off by default. It gates every route to a person: the assistant's own escalation, the widget's "Talk to a person", a "Talk to a human" Home button, and a handoff step in a flow. With it off, a customer who asks is told plainly that they cannot be put through — never parked in a queue nobody is watching.

With it on, the chat brain gains a request_handoff tool and escalates the moment somebody asks for a person, or when it cannot help. This is the path most escalations take: a Home button and a flow step both require the visitor to be somewhere specific, whereas asking in plain language works at any point in the conversation, in any language.

{
  "ready": false,
  "destination": "webhook",
  "checks": [
    { "id": "plan", "label": "Your plan includes live handoff", "ok": true },
    { "id": "enabled", "label": "Handoff is turned on for this chatbot", "ok": true },
    { "id": "team", "label": "Somebody can answer", "ok": true, "detail": "3 people on the roster." },
    { "id": "on_duty", "label": "Somebody is on duty", "ok": false, "severity": "warning" },
    { "id": "trigger", "label": "A customer can ask for a person", "ok": true },
    { "id": "destination", "label": "Your system is set up to receive handoffs", "ok": false,
      "detail": "No server URL yet, so handoffs have nowhere to go." }
  ]
}

1 — Register your operators

POST /inbox/operators/sync replaces the roster. Bolcho cannot know who was hired or who is on shift, so this is the one thing it must be told. Operators absent from a sync are marked unavailable, never deleted — a partial sync degrades to "nobody is available" rather than a wiped team and a broken audit trail. Then call POST /inbox/operators/heartbeat every ~30s from each open inbox.

2 — Choose how conversations are routed

Per chatbot, via PATCH /agents/{id}:

- manual — lands in a shared queue for someone to claim (the default)
- round_robin — the eligible operator who has gone longest without one
- least_busy — the eligible operator holding the fewest

Eligible means available, heartbeat fresh, covers this chatbot, and under maxConcurrent — all four. If nobody qualifies the conversation stays in the queue and the customer is told honestly; Bolcho will never invent an assignee to make a queue look tidy.

3 — Set the clocks

handoffSlaSec is how long a customer may wait for their first human reply before the conversation is flagged breached and raised in the queue. The clock stops on the first delivered reply, not on assignment — a claimed-then-ignored conversation is exactly the failure this measures. handoffAbandonSec marks a conversation abandoned after that much customer silence while still waiting; null means never.

Office hours

handoffHours on the assistant decides what an escalating customer is told. The handoff is never blocked — someone asking for a person has already decided the bot cannot help, and refusing to escalate strands them twice. What changes is the message and the expectation.

{
  "handoffEnabled": true,
  "handoffDestination": "webhook",
  "handoffRouting": "round_robin",
  "handoffSlaSec": 300,
  "handoffAbandonSec": 1800,
  "handoffAwayMessage": "We're closed until 9am — leave a message and we'll reply first thing.",
  "handoffBusyMessage": "Everyone is with another customer. We'll be with you shortly.",
  "handoffHours": {
    "timezone": "Asia/Kolkata",
    "days": { "mon": [{ "from": "09:00", "to": "18:00" }] },
    "holidays": ["2026-12-25"]
  }
}

Acting as one of your operators

Your app authenticates with ONE workspace API key but has many agents behind it. Send x-voxa-actor: <externalId> on every inbox action so Bolcho knows who is claiming, replying, transferring and resolving — otherwise every action is anonymous and ?mine=true returns everyone's work. Add x-voxa-actor-name to make the audit timeline readable. Both headers are ignored for dashboard (JWT) callers, so a logged-in user cannot act as somebody else.

Being told a customer is waiting

Two server messages carry the queue to you, so you never poll for it. Set a Server URL on the assistant and make sure Handoff requested and Customer replied are ticked under Server messages. Both are on by default for new assistants, and turning handoffEnabled on with a webhook destination subscribes them if they are missing — assistants created before those events existed keep whatever they were made with, and nothing is delivered for a type that is not ticked. That is the single most common reason an integration looks silent.

conversation-handoff fires once, on the transition into waiting — not on every message afterwards. Routing has already run, so assignedTo tells you who it went to (null means it is unassigned and anyone may claim it).

{
  "message": {
    "type": "conversation-handoff",
    "timestamp": "2026-08-19T08:20:48.869Z",
    "agent": { "id": "…", "name": "Support Assistant" },
    "conversation": {
      "id": "6e556ba1-…",
      "channel": "widget",
      "status": "handoff",
      "handoffAt": "2026-08-19T08:20:48.812Z",
      "customer": "Asha",
      "leadPhone": "+919876543210",
      "leadEmail": null
    }
  }
}

conversation-message fires when the customer says something more while one of your people owns the conversation, so their screen updates without polling.

{
  "message": {
    "type": "conversation-message",
    "timestamp": "2026-08-19T08:21:06.131Z",
    "agent": { "id": "…", "name": "Support Assistant" },
    "conversation": { "id": "6e556ba1-…", "channel": "widget", "status": "handoff" },
    "message": { "role": "user", "content": "are you there?" }
  }
}

Verifying it really came from us

When a signing secret is set we send x-voxa-signature: an HMAC-SHA256, hex-encoded, over the raw request bytes. Compute it over the body before any JSON parsing — re-serialising changes the bytes and the check will never match — and compare in constant time. The type is also in x-voxa-message, so you can route before parsing.

Catching up on what you missed

GET /inbox/changes?since= returns everything that changed after a timestamp, oldest first, with a nextSince cursor to store. Poll it every few minutes as a safety net — a deploy, a restart or thirty seconds of unreachability is enough to lose a handoff otherwise, and the customer is left waiting in a queue you were never told about. It also surfaces abandoned, which the main list cannot show.

How many people you may register

Seats are a plan limit. GET /entitlements returns limits.maxOperators alongside usage.operators, so you can render "3 of 5 agents" without hard-coding anyone's pricing. Going over returns 402 with code: "quota_exceeded", the limit and what you sent — and the whole sync is refused rather than trimmed, so you never end up believing more people are staffing the queue than really are. On a plan without live handoff every roster call returns 403.