Human handoff

When the agent can't help, or the visitor asks for a person, someone from your team can take over the conversation in the admin panel, reply as themselves, and hand it back.

Turning it on

Turn on behavior.handoff.enabled in the bot's Behaviour tab and publish. Then:

• the agent gets the handoff_to_human tool, and is told to use it when the visitor asks for a person or when it can't help (it passes a reason and a short summary for your team);
• the chat's menu offers Talk to a person.

Team members with the agent role or above can handle conversations.

What happens

1. Requested. The conversation becomes handoff_pending. The visitor sees "Connecting you with someone from the team...", and the agent keeps helping meanwhile. With behavior.leadCapture.when: before_handoff the chat also shows the lead form, so your team knows who they're about to talk to. Your team sees the request in the admin panel's inbox, and the handoff.requested webhook fires (with the reason and summary).
2. Accepted. The first person to take it over gets it: the conversation becomes human, the visitor sees "Ana joined the chat" and her name on her messages, and the agent stops answering (a voice conversation ends; the chat carries on in text). handoff.accepted fires.
3. Talking. Messages from your team appear in the chat with the person's name, and the visitor sees when they're typing. If the chat is closed, the launcher's count goes up and the message shows in a bubble next to it.
4. Handed back. The person returns the conversation to the agent: the visitor sees "Ana left the chat", and the agent picks up from there, knowing what was said. handoff.resolved fires.

Anyone on the team can also take over a conversation that didn't ask for it, from the inbox.

Your team can add internal notes to a conversation: other team members see them, the visitor and the agent don't.

When nobody is available

A request only goes to the team when someone can take it: within the bot's opening hours (behavior.hours, when enabled), and with someone from the team signed in, meaning an owner, admin or agent whose presence is online or away (in practice, someone with the admin panel open; presence goes to offline when their last tab closes, and for everyone when the server restarts).

• No one available: the request goes nowhere. The visitor sees the bot's offline text (texts.offline), and with behavior.handoff.offlineAction: lead_form (the default) the lead form, so your team can follow up. The agent is told to offer to take their details.
• Someone available, nobody accepts within behavior.handoff.acceptTimeoutSec (2 minutes by default): the visitor is told no one is available, and the agent apologises and offers to take their details.

With behavior.hours.scope: bot, the agent is offline outside hours too: a typed message gets the offline text (at most once an hour) and the lead form if lead capture is on, and no model is called.

From code

The team side is also in the REST API. These need a signed-in user (a session), not an API token, because messages are sent as that person:

Endpoint	What it does
POST /api/v1/conversations/{id}/takeover	Take over (accepting a pending request, or stepping in)
POST /api/v1/conversations/{id}/messages	Reply: { "text": "...", "internal": false } (internal: true for a team note)
POST /api/v1/conversations/{id}/typing	Show or hide the typing indicator: { "active": true }
POST /api/v1/conversations/{id}/release	Hand back to the agent
POST /api/v1/conversations/{id}/close	Close the conversation

GET /api/v1/conversations/{id} includes handoff: the latest request for a person (status, requestedBy, reason, summary, when it was requested, accepted and resolved, and who took it), or null.

On the page, the handoff event reports pending, active (with the person's name), ended and unavailable.