Hand off to a human

What it is

Human handoff is a Call Action type. When the chatbot decides a conversation needs a person, it runs the handoff action: the conversation is flagged as escalated, your team gets an email with the reason and a link straight to the transcript, and the visitor is told a human will follow up.

It is one of the six Call Action types, alongside Button, Notify team, Collect info, Custom API, and MCP server. See What are Call actions? for how the whole library fits together.

Handoff does not open a live chat window for your team to type into. Agentency has no live-chat inbox for staff. Handoff is an escalation signal: it tells you a specific conversation needs a reply from a person, and hands you the transcript so you can reply by email, phone, or whatever channel that customer used.

When you would use it

• The visitor asks for a human, an account manager, or a manager.
• The visitor is angry, or the same question has failed twice.
• The request is outside what you are willing to let a chatbot answer — a refund dispute, a legal question, a medical detail, a bespoke quote.
• You are in a regulated industry and want a person to sign off on anything that is not a plain factual answer.

A good rule: anything you would not want a wrong answer on should end in a handoff rather than a guess. Keep the risky exception out of the knowledge base and add a handoff action for it.

Where to find it

Open Dashboard → Chatbots → your chatbot → Actions, then select New action and pick Human handoff under Start from scratch.

Steps

1. Open the Actions tab and select New action.
2. In Start from scratch, choose Human handoff.
3. On the Details tab, give it a Name your team will recognise, such as Talk to a person.
4. Fill in When should the AI use this? in plain language. This single field decides how reliably the handoff fires — see the wording tips below.
5. Switch to Configure and set Notify email. Leave it blank to use your account email.
6. Optionally write a Message to the visitor (optional) — a short line that travels with the handoff, such as "A member of our team will email you within one business day."
7. Save, then open the Test tab, type a sample message like "this is useless, get me a person", and select Run test. The test is a sandbox: no email is sent and nothing is recorded.
8. When the test says "The AI would trigger this action", turn on Enabled and save.
9. Ask the same question in Test Chatbot to see the live behaviour end to end. See Try the test chat.

What the visitor sees

The visitor keeps talking to the same chat. There is no transfer screen, no queue position, and no "a colleague is typing" indicator.

What changes is the reply: the chatbot is instructed to tell the visitor — in their own language — that the team has been notified and someone will follow up shortly. Because the reply is generated, the exact wording varies; it will not be a fixed canned sentence.

The handoff is a terminal action. It does not fetch anything for the chatbot to read out, so the conversation continues normally afterwards. If the visitor keeps typing, the chatbot keeps answering from your knowledge.

What your team receives

The alert is an email, sent to the Notify email on the action. If that field is empty or does not contain a valid address, it falls back to the chatbot owner's account email — so a handoff is never silently lost because someone left the field blank.

The email is the same branded layout as the rest of Agentency's mail, written in the owner's saved language (the job runs on a background worker, so it uses the saved preference rather than the browser's). It contains:

• the chatbot's name;
• the reason the chatbot gave for escalating, in the visitor's language;
• the visitor's last message;
• a link straight to that conversation in your dashboard, so you can read what was already asked and answered before you reply.

Delivery runs in the background. That is deliberate: a slow mail server can never hold up the visitor's reply. It also means the email arrives a moment after the visitor sees the reply, not before.

Email is the destination available today. The delivery layer is pluggable — additional destinations can be added without changing how you configure the action — but do not plan around a destination you cannot select in the editor.

Where handoffs show up afterwards

Three places, and it is worth knowing which is which:

• The action's Run log. Each handoff is one run row with a status. Open it from the action card. See Call Action history.
• The conversation itself. The transcript is in Conversations, and the email links directly to it. See Read a conversation.
• The Handoff Rate KPI on your main dashboard — the share of conversations that were escalated to a human in the selected date range. A rising handoff rate usually means a knowledge gap, not a broken chatbot. See Dashboard KPIs.

The Conversations list does not currently carry a "handed off" badge or filter. Use the email link or the Run log to find the specific escalated conversation, and the KPI to watch the trend.

Writing a good "when should the AI use this?"

This description is the biggest single factor in whether a handoff fires at the right moment. Two rules:

Be specific about the trigger, not the outcome. "When the user needs help" fires constantly. "When the user explicitly asks to speak to a person, or repeats the same question after an answer that did not resolve it, or mentions a refund dispute" fires when you want it.

Say what should NOT trigger it. Adding "Do not use this for questions that are answered in the knowledge base" measurably cuts false escalations.

A worked example:

When the visitor asks to speak to a human, a manager, or the support team; when they express clear frustration; or when they raise a billing dispute, a refund over 200, or a complaint about a previous order. Do not use this for questions the knowledge base already answers.

Pair it with an instruction item on Settings → Instructions — for example, "Never promise a refund; offer to pass the case to a person." — so the tone around the handoff matches your policy. See Write instructions.

What you will see

In the library, the handoff action appears as a card with the Enabled badge, its run count, last run time, and success rate. The editor is a slide-over with three tabs: Details, Configure, and Test. In the Run log, a delivered handoff reads Success; one where no destination could be reached reads Failed with the reason Delivery failed.

Limits and plan notes

Handoff counts as one of your enabled Call Actions. Free includes 0, Starter 3, Standard 8, Pro 12, Agency 20 enabled actions per chatbot — so on Free you cannot enable a handoff at all. See Plans and what you get.

You need the permission to manage actions on that chatbot; a Viewer cannot create or enable one. See Roles and permissions.

Handoff makes no outbound call to your servers, so it is not subject to the outbound-API rate limit that Custom API actions are. It is still counted by the per-visitor and per-chatbot run caps that protect every action type.

Common problems

The chatbot never hands off, even when I ask for a human.

Check three things in order: the action is Enabled; the chatbot's AI model supports tool calling (if it does not, the Actions tab shows "Actions are temporarily unavailable" — see Chatbot AI settings); and the "when should the AI use this?" description names the phrasing your visitors actually use. Run the Test tab with a real visitor sentence to see which one it is.

It hands off far too often.

The description is too broad. Narrow it, add an explicit "do not use this for…" clause, and make sure your knowledge base actually answers the common questions — a chatbot with thin knowledge escalates to fill the gap. See Knowledge overview.

The run says Delivery failed.

No destination could be reached. Confirm the Notify email is a valid address and check the spam folder on that mailbox. The conversation is still flagged and the visitor was still told someone would follow up — only the email failed, so the escalation is still visible in your Run log.

Nobody on my team gets the email except me.

The action carries one email destination. Point it at a shared inbox or a distribution list your team already monitors rather than a personal address.

I turned it on but the Handoff Rate KPI is still zero.

The KPI counts conversations in the selected date range. A handoff you triggered from the Test tab is a sandbox run — it sends nothing and records nothing. Trigger it from Test Chatbot or a real visitor session instead, then re-check the date range.