This page covers the UI-based Call Handoff feature. Ask if your project uses the code-level
transfer_call function.Edit an existing destination
- In the sidebar, select Call handoffs.
- Hover over the destination you want and click Edit.
- Change the Number / SIP URI or Description.
- Save.
- Make a quick test call in Sandbox and confirm the transfer works, then promote your version.
| Reason | What to update |
|---|---|
| Front-desk line changed | Replace the number in Route |
| Routing after-hours | Add a note in Description so team mates know when to switch destinations |
Add a new handoff destination
- Click Add handoff.
- Fill in:
- Name — e.g. “VIP host desk”.
- Method — leave SIP REFER unless your telephony team says otherwise.
- Route / Number —
+1XXXXXXXXXXor a SIP URI. - (Optional) SIP headers if your PBX needs extra context (see next section).
- Add → test → promote.
Add SIP headers (optional)
SIP headers let you pass metadata — account ID, language, VIP flag, etc.- While creating or editing a destination, click Add SIP header.
- Enter a header name (custom headers start with
X-). - Enter a value, or use a variable such as
$caller_id. - Save.
Using your own Twilio number
If you bring your own Twilio DID:- Connect Twilio under Telephony → Twilio (enter Account SID + Auth Token).
- In Twilio, point the number’s Voice webhook at your agent URL.
- Back in Call handoffs, use that number as the Route field.
US numbers need A2P 10DLC registration for SMS.
Test before you ship
- Call the Sandbox number.
- Trigger the scenario that should transfer.
- Confirm the call operates how you are expecting.
- Promote the new version to Production.
- Number format (+ and country code)
- Firewalls or other rules on the destination side
- SIP header spelling
When to escalate
- You need more conditional logic the UI express
- The destination uses a non-standard SIP method
- You are seeing 4XX/5XX SIP errors