Human handoff

Transfer a conversation to a human agent. Configurable conditions, business-hours schedule, offline message, and contact capture.

The Human Handoff tool gives the chatbot a way to stop answering and hand the conversation over to a real person.

Tool description (verbatim)

Human Handoff — Transfer conversations to human agents when the AI can't help. Configure when and why handoffs happen.

When the chatbot uses it

The bot calls a handoff function named request_human_handoff with a short reason ("User asked for a person," "Topic is a refund," etc.). You don't set this up — the AI decides based on the Handoff Conditions you configure below.

Configuration fields

Enabling the tool shows a form with 11 fields. Every field has a default, so saving without edits gives you a working configuration.

Handoff Conditions (textarea, optional)

Default (verbatim):

Transfer the conversation to a human agent when:

  • The user explicitly asks to speak with a human
  • You cannot answer their question after trying
  • The topic involves complaints, refunds, billing issues, or sensitive matters
  • The user seems frustrated or dissatisfied with your answers

Do NOT transfer for simple questions you can answer from the knowledge base.

These conditions are injected into the chatbot's system prompt so the AI knows when to trigger a handoff.

Offline Message (textarea, optional)

Default: "Our team is currently offline. Please leave your message and we'll get back to you as soon as possible."

Sent as the chatbot's reply when a handoff is requested outside business hours (see Enable Schedule below).

Enable Schedule (checkbox)

Default: off.

When off, the tool ignores business hours entirely — every handoff request goes through. When on, the Available Days, Start Time, End Time, and Timezone fields below decide whether a handoff happens or the Offline Message is sent instead.

Available Days

Default: mon,tue,wed,thu,fri

Comma-separated three-letter day names: mon, tue, wed, thu, fri, sat, sun.

Start Time

Default: 09:00 (24-hour format).

End Time

Default: 18:00 (24-hour format).

The window is start ≤ now < end — the end time is exclusive (so 18:00 means up through 17:59).

Timezone

Default: America/Bogota.

Use a standard timezone identifier like America/Bogota, America/Argentina/Buenos_Aires, or Europe/Madrid. If the timezone isn't recognized, the tool treats agents as available.

Enabled Channels

Default: widget,whatsapp,telegram

Comma-separated: widget, whatsapp, telegram. Leave empty to enable the tool on every channel.

Collect visitor name/email before handoff (checkbox)

Default: on.

When on, the widget shows a small contact-capture form before the conversation is handed over, using the next two fields to decide what to ask for.

Contact capture mode

Default: required.

Either required (the visitor must fill the contact form before the handoff) or optional (they can skip it).

Fields to collect

Default: name,email.

Comma-separated, any combination of name, email, and phone.

What the visitor sees when a handoff happens

When the AI decides to hand off:

  1. Inside business hours — the chatbot replies: "I'm connecting you with a human agent. Someone from our team will be with you shortly." The widget shows the contact-capture form (if enabled), then the conversation flips to Needs Reply and a teammate can pick it up.
  2. Outside business hours — the chatbot sends your Offline Message instead, and the conversation stays as-is.

How conditions affect the AI's behavior

The Handoff Conditions and the current schedule status (AVAILABLE or OFFLINE) are both added to the system prompt for each conversation, so the AI knows:

  • "Human agents are currently AVAILABLE." when the schedule is on and we're within hours
  • "Human agents are currently OFFLINE. If the user requests a human, inform them agents are unavailable and offer to take a message." when the schedule is on and we're outside hours
  • Nothing when the schedule is off

Plan notes

Enabling tools requires the AI Tools feature, which unlocks on Growth — $79/mo. See Plans & pricing.

← Previous
Lead capture
Next →
Wasi real estate