Looking to manage handoff states programmatically? Visit the API documentation.
handoff Use Call Handoffs to define destinations for customer-call routing. The typical use case for a handoff is a scenario where the agent cannot handle a query and a live, human agent is required.

​
Adding a handoff destination

To create a new handoff destination:
  1. Go to the Call Handoffs section in the Build menu.
  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 caller 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.
  4. Click Add to save the destination.
handoff

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

​
Managing handoffs

Once a handoff destination is created, it will appear in the list of destinations. You can edit, delete, or update the details as needed.
  • Example: A customer support agent might have a handoff destination called “Billing Support” to route calls related to payment issues.

​
Best practices for call handoffs

  • Use clear descriptions: Ensure handoffs are labeled with their intended use to avoid confusion.
  • Test call routing: Regularly test handoff destinations to verify they are functioning correctly.
  • Optimize SIP headers: Use headers to pass relevant metadata and improve call handling.

​
New: Handoff reason and utterance

​
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”).

​
Important for US Numbers: Register for A2P 10DLC

If you are using a US-based Twilio number, you must register for A2P 10DLC to comply with regulatory requirements. Twilio will block SMS messages if this is not completed.

​
Register

  1. Go to Twilio’s A2P 10DLC registration page: Twilio A2P 10DLC Registration Guide
  2. Complete brand and campaign registration to comply with US carrier regulations.
  3. Wait for approval (can take a few days).
  4. Once approved, messages will send successfully.

​
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.
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. If you’re using transfer_call in a function, it overrides any configured Call Handoff in the UI.

​
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).
Troubleshooting: If your messages fail to send, check the Twilio logs for these error codes: