> ## Documentation Index > Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt > Use this file to discover all available pages before exploring further. # Warm Handoff > Transfer the caller to a human agent, with a private handoff summary spoken to that person before the calls are merged. ## Description Use **Warm Handoff to Human Agent** when the assistant should transfer the caller to a person and brief that person privately before merging the calls. Good fits: * Transfer qualified callers to sales, support, claims, or bookings teams * Escalate calls that need a human decision * Connect callers to a known phone number while preserving context from the conversation *** ## What Happens 1. The tool dials the human agent. 2. It checks for voicemail. If voicemail is detected, the handoff fails. 3. It privately speaks a short summary to the human (the caller does not hear this). 4. It merges the caller and the human together. 5. The assistant speaks the **Warm Merge Message** so both parties know the handoff has happened. If the handoff fails, the assistant can speak a **Failure Message** and continue the flow. *** ## Manual Inputs | Name | Data Type | Required | Description | | -------------------------------------- | --------- | -------- | -------------------------------------------------------------- | | Agent Name | string | Yes | Name or label of the person/team being connected | | Phone Number | string | Yes | Number to dial, in E.164 format | | Warm Merge Message | string | Yes | Spoken after the caller and human are connected (both hear it) | | Failure Message | string | No | Spoken if the handoff cannot be completed | | Hold Music | string | No | Audio the caller hears while dialing | | Failure Override – Return to Last Step | bool | No | Send the caller back to the previous step after failure | | Calendar Setting | string | No | Only allow the handoff during configured business hours | | Handoff Initiated Message | string | No | Spoken to the caller before dialing starts | | Wait For User | bool | No | Wait for the human to speak before the private summary | | Wait For User Message | string | No | Target phrase from the human before the summary is spoken | | Summary Inputs | string | No | Extra context/instructions for the private summary | | Handoff Timeout Seconds | number | No | How long to wait for the human to speak | ### Agent Name The name or label of the person or team being connected — `Sarah`, `Claims Team`, `Property Manager`, `Support`. Used in logs, transcript labels, and fallback handoff text. Use a name the caller would understand. ### Phone Number The number to dial. Use E.164 format where possible: ```text theme={null} +61412345678 ``` Do not use spaces, local-only numbers, or display labels unless the telephony provider explicitly supports them. ### Warm Merge Message Spoken after the caller and human are connected. **Both parties hear this**, so keep it short and do not include the private summary here. * `Thanks for waiting. I've got Sarah on the line now.` * `I've connected you with our claims team. They can help from here.` ### Failure Message Spoken if the handoff cannot be completed and the caller is still on the line. Make it a useful recovery line, and avoid saying the call is ending unless the flow will actually end. * `I wasn't able to connect you just now, so I'll keep helping here.` * `The team is not available at the moment, but I can continue taking the details.` ### Hold Music The audio the caller hears while the tool dials and prepares the handoff. Available options: * `handoff-jazz-lounge-1` * `handoff-jazz-lounge-2` * `handoff-jingle-1` * `handoff-rhythm-1` * `handoff-rhythm-2` * `handoff-slow-latin` * `office-ambience` Use calmer music for longer expected waits, lighter sounds when handoffs are usually quick. ### Failure Override – Return to Last Step Controls recovery behavior after a failed handoff. Use `false` when the flow can continue from the current step. Use `true` when the caller should be sent back to the previous step or a retry path. This does not make the handoff more likely to succeed. ### Calendar Setting Optional availability guard. When set, the handoff only happens during the configured window — outside it, the tool skips dialing and speaks an out-of-hours style failure message. Leave blank when the number can be dialed any time. ### Handoff Initiated Message Optional message spoken to the caller (only) before dialing starts, to set expectations before hold music begins. Keep it short and avoid promising success. * `One moment, I'll try connecting you now.` * `Sure, I'll see if someone is available.` ### Wait For User Controls whether the assistant waits for the human side to speak before giving the private summary. * `false` — normal handoffs; the assistant proceeds after the voicemail check. * `true` — wait for the human to answer or say something first. Useful for shared lines, reception queues, or team phones where you want to confirm someone is present. ### Wait For User Message Optional target phrase for the human side, used with **Wait For User**. The match is semantic, so minor wording differences still pass. Leave blank if any human speech should trigger the summary. * `Hello, this is support.` * `Claims team speaking.` ### Summary Inputs Extra instructions or context for the private summary spoken to the human before merge. Use it to tell the summary what details matter. **Do not put caller-facing text here** — this summary is for the human agent. * `Include the customer's name, reason for calling, and requested appointment time.` * `Include policy number: {data_contact.policy_number}` Simple placeholders in braces can be resolved before the summary is generated. ### Handoff Timeout Seconds Optional timeout for waiting on the human side to speak before the private summary. Used mainly with **Wait For User**. | Value | Use | | ----- | ------------------------------------------------ | | `5` | Fast handoff, direct lines | | `10` | Balanced default for most live-answer checks | | `20` | Slower queues or teams that take longer to greet | Leave blank to use the tool's default behavior. *** ## Manual Outputs | Name | Data Type | Description | | ------ | --------- | ------------------------------------------------------------ | | result | bool | `true` if the handoff completed and the call was transferred | *** ## Conditions ### Success (true) The handoff completed and the call was transferred to the human. ### Failure (false) The handoff was skipped or failed — outside configured hours, voicemail detected, no answer, request failure, timeout, or telephony error. *** ## Example Usage Simple sales handoff: ```text theme={null} Agent Name: Sales Team Phone Number: +61412345678 Warm Merge Message: Thanks for waiting. I've connected you with our sales team now. Failure Message: I wasn't able to connect you just now, so I'll keep helping here. Hold Music: handoff-jazz-lounge-1 ``` Support handoff that waits for a greeting: ```text theme={null} Agent Name: Support Phone Number: +61412345678 Warm Merge Message: You're now connected with support. They'll help from here. Wait For User: true Wait For User Message: Hello, this is support. Handoff Timeout Seconds: 10 Summary Inputs: Include the caller's name, issue, and any troubleshooting already attempted. ``` Business-hours handoff: ```text theme={null} Agent Name: Reception Phone Number: +61412345678 Warm Merge Message: I've connected you with reception now. Calendar Setting: configured office hours Failure Message: Reception is unavailable right now, but I can keep helping. Failure Override - Return to Last Step: true ``` *** ## Common Issues * **The handoff never starts** — check Calendar Setting, required inputs, and the phone number format. * **Returns `false` after dialing** — the human may not have answered, voicemail may have been detected, or telephony returned an error. * **Callers wait too long** — reduce Handoff Timeout Seconds or turn off Wait For User. * **The human hears too little context** — improve Summary Inputs. * **The caller hears information meant only for the human** — move it out of Warm Merge Message and into Summary Inputs. *** ## Best Practices 1. **Keep caller-facing messages short** 2. **Use Wait For User only when it solves a real routing problem** 3. **Use Summary Inputs** to highlight details a human must know immediately 4. **Configure business hours** when dialing a human outside hours would create a bad experience 5. **Test each destination end to end** — including voicemail, no-answer, and after-hours behavior *** ## Next Steps * [Tool Steps](/flows/steps-tool) — Learn how to configure tool steps * [Variables](/flows/variables) — See all available variables