Set Up Team Handoff So a Real Person Gets the Context

Every assistant hits a question it should not answer. The difference between a good deployment and a bad one is what happens next — whether the visitor gets a dead end and a shrug, or whether someone on your team receives enough context to pick up where the assistant left off.

Hand-off is not a feature you turn on. It is a route you configure, and its quality is entirely down to how well you describe it.

Where it lives

Open your assistant and go to the Channels tab. Under the Escalation group is the Human Handoff card. Its header shows how many escalation channels you have configured — if that number is zero, the assistant has no way to reach you, whatever your instructions say. You can save up to five per assistant; most sites need one or two.

How a conversation actually reaches a person

The assistant does not guess. When you have at least one enabled escalation channel, it is given a tool for reaching your team, and it calls that tool when a visitor asks for a person, when it cannot resolve the issue, or when the subject is billing, account access, a complaint or something similarly sensitive. This works in text chat and voice alike.

One guardrail matters before you configure anything. Because both routes below are answered by your team later, the assistant must have a way to reach the visitor back. With neither an email address nor a phone number for them, the escalation is rejected and the assistant is told to collect the details and try again. That check runs on the server, so it holds regardless of what the browser sends. The exception is a visitor who was asked and explicitly declined; the request then goes through rather than being lost.

The practical consequence: a good hand-off collects contact details during the conversation, not as a form at the end.

The four controls every channel has

Whatever type you pick, the same four settings appear:

Description is the field people skim, then wonder why hand-offs go to the wrong place. It is how the model decides which channel fits. With one channel it barely matters; with two it decides everything.

Write them as instructions to a new colleague deciding which queue to drop a ticket into.

Option 1: Email

The simplest route, and the right default for most teams.

1. Click Add channel in the Human Handoff card and set Channel Type to Email.
2. Enter the Support Email the escalation should go to, and optionally a CC address.
3. Leave Include conversation transcript on — it attaches the last 20 messages.
4. Write a Display Name and a Description.
5. Leave Enabled on, and Save the assistant.

Display Mode decides who sends the email:

• Inline in Chat — Hiroi sends it. The message carries the urgency the assistant assigned, its summary of what the visitor wants, and the visitor's name and contact details. The visitor sees a confirmation in the chat; if sending fails, a retry button appears instead.
• Open in Popup Window — the visitor gets a Send Email button that opens their own mail client. Hiroi sends nothing.

For a support queue you almost always want Inline in Chat. Popup mode hands the work back to the visitor, and a meaningful share will not finish it.

Point it at a shared inbox rather than a person. Escalations landing in one individual's mail is how a hand-off silently stops working the week they take leave.

Option 2: Webhook

Use this to push escalations into your own systems — a ticket queue, an on-call pager, a relay you host.

1. Add channel, set Channel Type to Webhook.
2. Enter your Webhook URL and pick an HTTP Method — POST, PUT or PATCH.
3. Write a Display Name and Description, leave Enabled on, and Save.

Hiroi sends a JSON body shaped like this:

{
  "event": "escalation",
  "site_id": "...",
  "site_name": "Acme Support",
  "visitor": { "name": "Dana Reed", "email": "dana@example.com" },
  "issue": {
    "reason": "Card declined on renewal",
    "summary": "Wants the renewal retried on a new card before Friday",
    "urgency": "high"
  },
  "transcript": [ { "role": "user", "content": "..." } ]
}

urgency is low, medium or high — route on it. transcript is capped at the last 20 messages, each truncated to 500 characters.

Delivery rules worth designing around: requests time out after 10 seconds, redirects are not followed, and URLs resolving to a private address are refused. Any status below 400 counts as delivered; anything else shows the visitor a retry button. So respond fast and respond 200 — do the real work asynchronously rather than making the visitor wait on your ticket system.

One limitation to be explicit about: this delivery is not signed, and there is no delivery log. If you need to verify the request came from Hiroi, or a record of every attempt, use an Action instead — the signed, logged, retried version of the same idea, on the Intelligence tab.

Tell the assistant about the hand-off in its instructions

Configuring a channel gives the assistant the ability to escalate. Your Instructions on the General tab decide whether it does so gracefully. Two lines are usually enough:

When you cannot answer confidently, say so plainly and offer to pass it to the team rather than guessing. Before doing that, ask for their name and an email address so we can reply. Do not promise a response time.

That last clause matters more than it looks. Left to itself, an assistant will invent "someone will get back to you within the hour," and you will own that promise. Set Up Your Assistant's Persona and Tone covers the rest of that field.

Test it before you rely on it

An untested hand-off is worse than none, because you will assume it is working.

1. Save the assistant, then open Test Widget on the Deploy tab.
2. Ask something the assistant genuinely cannot answer, then ask for a person.
3. Watch it collect your name and email. If it escalates without asking, your instructions need the line above.
4. Confirm the visitor-side confirmation appears in the chat.
5. Check the destination. For email: did it arrive, is the transcript attached, is the summary good enough for a colleague to act on without reading the whole thing? For a webhook: log the raw body and check urgency and issue.summary are populated.
6. Fix whatever was thin, and run it once more.

Repeat the test after any change to the channel — swapping a Display Mode or an address is exactly the kind of edit that silently breaks the route.

Two things to watch once it is live

The escalation endpoint is deliberately rate-limited, more tightly than anything else the widget calls. A handful of hand-offs per minute is far more than a real site produces; the cap stops a loop in a custom integration flooding your inbox. Refusals mean a loop, not a traffic problem.

Escalations are a content signal. If the same category of question keeps reaching a human, that is not a hand-off working well — it is a knowledge gap with a human patching it. A week of escalation emails usually contains two or three questions that should have been answerable. Those belong in the knowledge base: Building a Knowledge Base Your Assistant Can Actually Use covers how.

One measurement note: the Self-served tile in Analytics counts hand-offs to a live agent queue, not escalations sent by email or webhook. Here, your inbox is the measure — Reading Your Assistant Analytics explains the rest of that page.

The short version

Configure one email channel pointing at a shared inbox, transcript on, Inline in Chat selected. Write a description that says when to use it. Add a line to your instructions telling the assistant to collect a name and email first and not to promise a response time. Test it end to end, then read the escalations weekly and turn the recurring ones into documents.

That is a hand-off that holds up. You can set one up on any assistant at hiroi.ai.