Skip to main content
Developer content — This page requires Python familiarity. If you’re configuring the UI only, you can skip this section. Non-technical operators should share this page with their developer.
Call handoff configuration
Prerequisites: Understanding of SIP telephony or your contact center’s routing setup. UI-based handoff configuration (adding destinations, setting SIP headers) does not require code. The transfer_call function path requires Python — see the comparison table below. You can also find this page in the Developer tab.
Use handoffs when the agent reaches a point where a human needs to take over — billing disputes, complaints, or requests outside the agent’s scope. A well-configured handoff routes the caller to the right team with context intact; a missing or misconfigured handoff leaves callers stuck or dropped.
Use Call Handoffs (UI-based) when you have fixed transfer destinations with straightforward routing. Use transfer_call (code-based) instead when you need dynamic routing logic, custom SIP headers, or integrations like Zendesk. See the comparison table below for details.
The SIP-based handoff methods described below apply to voice interactions. Webchat handoffs use HTTP-based integrations with your live chat platform. To manage handoff states programmatically, visit the Handoff API documentation.

​
Adding a handoff destination

To create a new handoff destination:
  1. Go to Build > Call handoffs in the sidebar.
  2. Click Add Handoff.
  3. Fill in the following details:
    • Name: Enter a descriptive name (e.g., “Front desk”).
    • Description: Add a note about when to use this handoff (e.g., “When the user needs to speak with an operator”).
    • Method: Choose the SIP method to use for call routing. Options include:
      • SIP REFER (default) – PolyAI specifies a transfer destination to the client (SBC), then drops from the call.
      • SIP INVITE – PolyAI creates a new call with the destination and acts as a bridge between the client SBC and the destination.
      • SIP BYE – PolyAI signals that its call leg is over, allowing the client SBC to take the call back over.
  • Route: Specify the destination SIP URI or extension (only applies to SIP INVITE and SIP REFER).
  • SIP headers: Add optional SIP headers to include metadata or routing instructions.
  1. Click Add to save the destination.
Adding a handoff destination

​
Configuring SIP headers

SIP headers can be used to send additional metadata when making a handoff. To add SIP headers:
  1. Click Add SIP Header in the handoff setup modal.
  2. Enter a Header Name (e.g., X-Customer-ID).
    • Custom headers should start with an X- prefix.
  3. Enter a Value (e.g., abc123).
  4. You can use variables prefixed with $ in the SIP header values for dynamic data. Example: X-Caller-ID: $caller_id
  5. Repeat as needed for multiple headers.
SIP headers allow for custom integrations with external telephony systems and can help manage call behavior dynamically.

​
Default handoff

One handoff destination can be marked as the default. This is the fallback destination used when no specific routing matches — for example, when the caller requests a transfer but no topic or flow step maps to a specific handoff.
  • The first handoff you create is automatically set as the default.
  • To change the default, open the actions menu on a handoff card and select Set as default.
  • If the default handoff is deleted, you should assign a new default to avoid unrouted transfers.

​
Managing handoffs

Once a handoff destination is created, it will appear in the list of destinations. From the actions menu on each card, you can:
  • Edit — modify the name, description, method, route, or SIP headers
  • Duplicate — create a copy of an existing handoff for a similar destination
  • Delete — remove the handoff (requires typing the name to confirm)
  • Set as default — mark as the fallback handoff destination

​
Encryption options

When using SIP INVITE, you can choose the transport encryption:
OptionDescription
TLS/SRTP (default)Encrypted transport. Use this unless your destination requires unencrypted traffic.
UDP/RTPUnencrypted transport. Some legacy systems require this.
Encryption only applies to SIP INVITE. SIP REFER and SIP BYE delegate transport to the carrier or SBC.

​
Integration-level constraints

Your telephony integration (e.g. Twilio, SIP trunk) may impose constraints on handoff configuration. When constraints are active:
  • The SIP method dropdown may be locked to a specific method (e.g. all handoffs must use SIP REFER)
  • The route/phone number field may be hidden if routing is handled by the carrier
  • The SIP headers section may be hidden if the integration does not support custom headers
If a handoff’s method does not match the integration’s required method, a warning appears on the handoff card. Update the handoff to match, or the transfer may not work as expected.

​
Best practices for call handoffs

  • Use clear descriptions — label handoffs with their intended use (e.g. “Billing disputes” not “Team A”)
  • Always have a default — ensure one handoff is marked as default so unmatched transfers have a destination
  • Test in sandbox — verify handoff destinations route correctly before promoting to Live
  • Use SIP headers for context — pass metadata like X-Customer-ID or X-Reason so the receiving system can route or display caller context

​
Handoff reason and utterance

The built-in handoff template and the conv.call_handoff() helper accept two optional, structured fields:
FieldPurposeExample
reasonMachine-readable code explaining why the call is being escalated (e.g. policy_violation, needs_human, no_availability). Surfaces in Conversation Review and the Conversations API.policy_violation
utteranceA short message the agent delivers before transfer begins (spoken for voice, displayed for webchat). Logged alongside the handoff for QA review.”Let me transfer you to a specialist who can help.”
When using SIP REFER, the utterance may not play before the transfer completes because the REFER fires at the same time as function execution. If you need the utterance to be spoken reliably before transfer, use SIP INVITE instead.
Where it shows up
  • Flows & KB actions – Selecting builtin-handoff displays Reason and Pre-handoff utterance fields.
  • Functions – Call conv.call_handoff(destination="...", reason="...", utterance="...") to escalate programmatically.
  • Conversation Review – Both fields appear in the metadata panel for quick troubleshooting.
  • Conversations API – Returned inside the handoff object for BI dashboards or CRM routing.
Benefits
  • Removes guesswork when diagnosing handoffs — no more relying on LLM summaries alone.
  • Enables fine-grained routing rules in telephony or CRM systems.
  • Gives QA teams full visibility into the exact wording customers heard.

​
Using your own Twilio number

If you’re bringing your own Twilio phone number to route calls, follow these steps to integrate it as a handoff destination:
  1. Connect your Twilio account:
  2. Assign a Twilio number:
    • Choose a number from your Twilio account to use for routing calls.
    • If necessary, provision new numbers directly using the Twilio console.
  3. Set up routing in Twilio:
    • Configure your Twilio number to route calls to your PolyAI agent by setting the Webhook URL in your Twilio console. Example:
      • Voice Webhook URL: https://your-polyai-instance-url/voice/call
    • Make sure your webhook supports POST requests and uses the correct authentication methods.
  4. Add the Twilio number as a handoff destination:
    • In the Call Handoffs section, use the Twilio number as the “Extension / Number” field when creating a new destination.
    • Add a description specifying its purpose (e.g., “Route to Twilio-based live agent team”).
If you are using a US-based Twilio number for SMS, you must register for A2P 10DLC to comply with regulatory requirements. See the Twilio handoff guide for more details on Twilio-specific configuration.

​
Comparison: Call Handoff and the transfer_call function

These two methods serve similar purposes — routing the user to another endpoint — but are mutually exclusive and differ in flexibility and implementation.In the table below, means the feature is supported and — means it is not supported.
FeatureCall Handoff (UI-based)transfer_call (code-based)
Ease of setup UI form— Requires Python editing
Works in flow builder
Works in Function Editor—
Dynamic routing logic— Full control
Supports custom metrics—
Supports soft-handoff—
Best for static SIP integration—
Best for dynamic integrations— (e.g. Zendesk)
These two methods cannot be used together in the same step. transfer_call overrides any configured Call Handoff in the UI. If you use transfer_call, keep destination mappings in sync manually — changes in the Call Handoff UI are not reflected in function-based transfers.
The UI-based Call Handoff does not support custom metrics. Use transfer_call with conv.write_metric() if you need handoff reason codes for analytics.

​
When to use each method

Use Call Handoff if:
  • You want a quick setup through Agent Studio with minimal code.
  • Your routing needs are straightforward and based on static values.
Use transfer_call if:
  • You need to pass dynamic SIP headers (e.g., customer metadata).
  • You want to use soft handoffs or log custom handoff metrics.
  • You’re integrating with a platform that does not support SIP REFER (e.g. Zendesk).
Need code-based routing? There is a transfer_call Python function for dynamic handoff logic, custom SIP headers, and integrations like Zendesk. Switch to Full docs in the top navigation to compare both methods.

Handoff States API

Monitor transitions between automated and live agents.

Handoff API reference

Retrieve handoff context programmatically.

Twilio handoff

Twilio-specific handoff configuration.
Last modified on March 31, 2026