Skip to main content

​
Description

Use the Handoff tool when the assistant should transfer the caller to a person. In a warm transfer it briefs that person privately before merging the calls. In a cold transfer it puts the caller straight through. Good fits:
  • Transfer qualified callers to sales, support, claims, or bookings teams
  • Escalate calls that need a human decision
  • Connect callers to a configured routing endpoint — a team, queue, or direct line — while preserving context from the conversation

​
What Happens

  1. The tool dials the human agent at the selected routing endpoint.
  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 Merge Message so both parties know the handoff has happened.
The steps above describe a warm transfer. In a cold transfer, the tool dials the endpoint and hands the caller over straight away, without the private briefing or a merge message. While the destination rings, the caller hears a ringback tone, and any carrier announcement (such as “the number you have called is not available”) reaches them too. You choose between the two with the Transfer Mode input. On both warm and cold transfers, the destination is rung for up to the Ring Timeout (300 seconds by default). If nobody answers in that time, or the line is busy or rejects the call, the call comes back to the script: the Failure Message is spoken if you set one, the step routes to Otherwise, and the flow carries on. The tool also records why it failed in the {{handoff.*}} variables, so the flow can respond differently to a busy queue and a number that rejected the call outright. See Variables this tool writes. Hold music starts about half a second after the assistant’s last word, so it doesn’t cut in over the end of a sentence. While a handoff is in progress (from the moment dialling starts until the transfer connects or fails), the script’s Max Call Duration clock is paused, so a long ring doesn’t use up the conversation’s time. A transfer that connects gets its own 30-minute allowance. Web calls can be handed off too. The assistant dials the person on one of your team’s phone numbers and joins them to the browser caller, converting the audio between web and phone quality automatically. The number to dial from is worked out once at the start of the call: the script’s number first, then the team default, then any number on the team. That order is tried first with numbers in the call’s own environment (Test or Live), then again across both environments. If none of those is usable, the handoff fails on the Otherwise condition rather than dialling without a valid caller ID. Out-of-hours handling is not a setting on this tool. Whether the handoff can run outside business hours is governed by the schedule attached to the routing endpoint you dial — see Routing Endpoints and Schedules.

​
Manual Inputs

The inputs appear in this order in the tool panel:

​
Warm Handoff - Agent Name

The name or label of the person or team being connected — Sarah from claims, Claims Team, Property Manager, Support. Used in logs, transcript labels, and the private summary. Accepts literal text or a {{...}} variable (type / in the field to insert one). Use a name the caller would understand.

​
Routing Endpoint

The dial destination. Rather than typing a raw phone number, you select a routing endpoint — one of the destinations your team has set up under Numbers & Routing. The endpoint you pick supplies two things:
  • the number the tool dials, and
  • the open-hours schedule that decides whether the handoff can run right now.
Because the schedule travels with the endpoint, you set business hours once on the endpoint and every step that dials it inherits them — there is no phone-number field on this tool and no separate hours setting. See Routing Endpoints for how endpoints are configured, and Schedules for how their open hours are defined.

​
Transfer Mode

How the transfer happens. Choose one:
  • Warm — the assistant plays hold music to the caller, dials the endpoint, optionally waits for the human to answer, speaks a private summary to them, then merges the two calls and speaks the Merge Message so both parties know the handoff has happened. The assistant then goes silent.
  • Cold — the assistant hands the caller over as soon as the endpoint starts ringing, with no private briefing and no merge message. The caller hears a ringback tone until someone answers. If nobody answers within the Ring Timeout, or the line is busy or rejects the call, the caller is brought back to the assistant and the script continues on the Otherwise route.
Warm is the usual choice when the human benefits from context. Use cold for straight transfers where no briefing is needed. Set a Merge Message for warm transfers — the app asks for one. If it is ever blank on a warm transfer, the assistant says “Thanks for holding, you’re now connected.” instead.

​
Warm Handoff - Merge Message

Spoken after the caller and human are connected in a warm transfer. Both parties hear this, so keep it short and do not include the private summary here. Accepts literal text or {{...}} variables (type / to insert one). Cold transfers do not use this message.
  • Thanks for waiting. I've got Sarah on the line now.
  • I've connected you with our claims team. They can help from here.

​
Handoff Initiated Message

Optional message spoken to the caller (only) before dialling starts, on warm transfers, to set expectations before hold music begins. Cold transfers never speak it — to announce a cold transfer, say it in a step before the Handoff step. It plays uninterruptibly — the caller cannot barge in over it — so keep it short and avoid promising success.
  • One moment, I'll try connecting you now.
  • Sure, I'll see if someone is available.

​
Ring Timeout

How long to ring the destination, in seconds, on both warm and cold transfers. When it runs out, the call returns to the script under the Failure Message rules. The help text reads: “How long to ring the transfer target, in seconds, on warm and cold handoffs. When it expires the call returns to the script with the Failure Message rules. Blank uses the Warm Handoff - User Summary Timeout capped at 300 s, or 300 s if that is blank too.” The value is kept between 10 and 600 seconds. Ring time doesn’t count towards the script’s Max Call Duration.

​
Failure Message

Spoken when the handoff can’t be completed and the call returns to the script, on warm and cold transfers alike. The help text reads: “Leave blank to return to the next step or the failure override silently.” 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.

​
Warm Handoff - Hold Music

The audio the caller hears while the tool dials the endpoint and prepares a warm handoff. The dropdown offers:
  • Jazz lounge 1
  • Jazz lounge 2
  • Jingle 1
  • Rhythm 1
  • Rhythm 2
  • Slow latin
Use calmer music for longer expected waits, lighter sounds when handoffs are usually quick.

​
Warm Handoff - 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.

​
Warm Handoff - 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.

​
Warm Handoff - 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. Accepts literal text and {{...}} variable references (type / to insert one).
  • Include the customer's name, reason for calling, and requested appointment time.
  • Caller name: {{contact.full_name}}. Claim: {{custom.claim_id}}.
Any {{...}} variables are resolved to their current values before the summary is generated.

​
Warm Handoff - User Summary Timeout

Warm transfers only. How long, in seconds, to wait for the person who answered to speak before the private summary is given up on. It is not the ring time; that is Ring Timeout.
  • With Wait For User off, it bounds the quick check that a person (not voicemail) has answered. Blank means 10 seconds.
  • With Wait For User on, it bounds the whole wait for the person to speak. Blank means no limit.

​
Failure Override - Return to Last Step

Controls recovery behaviour 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.

​
Manual Outputs

​
Conditions

​
Success (true)

The handoff completed and the call was transferred to the human.

​
Failure (false)

The handoff was skipped or failed — the routing endpoint was outside its scheduled hours, voicemail detected, no answer within the Ring Timeout, busy, rejected, request failure, or telephony error. This applies to cold transfers as well as warm ones.

​
Variables this tool writes

Every handoff attempt records its outcome in the {{handoff.*}} variables. Later steps can read them to work out what happened, instead of guessing from a single true-or-false result. The whole last.* group is overwritten on every attempt, so it always describes the most recent one and never mixes values from two attempts.

​
What {{handoff.last.status}} can be

​
Branching on the outcome

Route the tool’s own Otherwise condition to a recovery step, then use a condition on {{handoff.last.status}} to decide what the assistant says. This lets the assistant give each caller a reason that matches what actually happened.
Treat an empty or unfamiliar status the same way you treat timeout, so an unexpected value still lands on a sensible line. You can also use {{handoff.attempts}} to stop retrying — for example, only offer a second attempt while {{handoff.attempts}} is less than 2.

​
The two conditions on the step

  • Success (true) — the handoff completed and the caller was transferred. The flow pauses permanently: no later steps run, so never place post-handoff logic on the success route expecting it to execute.
  • Failure (false) — the handoff was skipped or failed, on a warm or a cold transfer. The Failure Message is spoken (if set) and the flow continues from the current step; with Failure Override – Return to Last Step set to true, the caller is sent back to the previous step instead. Read {{handoff.last.status}} here to find out why.
For how variable references work across scripts and tools, see Variables.

​
Example Usage

In the app you pick the Routing Endpoint from your team’s configured endpoints; the examples below show the endpoint’s name in that field, not a phone number. Simple sales handoff (warm):
Support handoff that waits for a greeting (warm):
Reception handoff — business-hours gating comes from the routing endpoint’s schedule, not a tool input:
Cold transfer — connect straight through with no briefing (no Merge Message needed):

​
Common Issues

  • The handoff never starts — check the routing endpoint’s schedule and that all required inputs are set.
  • Returns false after dialling — read {{handoff.last.status}} on the failure route to see whether it rang out, was engaged, was rejected, or hit voicemail.
  • Every failure sounds the same to the caller — branch the failure route on {{handoff.last.status}} so the assistant says something that matches what actually happened.
  • Callers wait too long while it rings — lower the Ring Timeout.
  • Callers wait too long after someone answers — lower the Warm Handoff - User Summary Timeout or turn off Wait For User.
  • Nobody answers a cold transfer — the call returns to the script after the Ring Timeout. Set a Failure Message and route Otherwise to a useful recovery step.
  • The human hears too little context — improve Summary Inputs.
  • The caller hears information meant only for the person — move it out of Warm Handoff - 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. Set business hours on the routing endpoint’s schedule when dialling a human outside hours would create a bad experience
  5. Test each destination end to end — including voicemail, no-answer, and after-hours behaviour

​
Next Steps