Quick reference
| I need to… | Action | Time estimate |
|---|---|---|
| Update a phone number | Edit destination → Change number → Save | 2 min |
| Add a new handoff destination | Add handoff → Fill details → Save | 5 min |
| Add SIP headers | Edit destination → Add SIP header → Save | 3 min |
| Test a handoff | Call Sandbox → Trigger transfer → Verify | 5 min |
| Connect Twilio number | Telephony → Twilio → Enter credentials | 10 min |
| Fix failed transfer | Check number format, firewall, SIP headers | 10 min |
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.
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 Live.
- Number format (+ and country code)
- Firewalls or other rules on the destination side
- SIP header spelling
Common workflows
Updating after-hours routing
- Identify which handoff destination handles after-hours
- Update the phone number or SIP URI
- Test in Sandbox during and after business hours
- Publish and promote to Live
Adding a new department handoff
- Get the phone number or SIP URI from the department
- Add new handoff destination with clear name
- Update Managed Topics to reference the new handoff
- Test the full flow in Sandbox
- Publish and promote
Related pages
- Call handoff overview - Complete handoff documentation
- Twilio integration - Twilio setup guide
- Function-based transfers - Code-level transfer control
- Version management - Safe deployment practices
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