Handoff

Set up handoff destinations for your agent to route calls during conversations.

Looking to manage handoff states programmatically? Visit the API documentation.

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 Session Border Controller (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.

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

Handoff reason and utterance

The built-in handoff template and the conv.handoff() helper now accept two optional, structured fields:

Field	Purpose	Example
reason	Machine-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
utterance	A short sentence the agent should speak before transfer begins. Logged alongside the handoff so QA can hear exactly what callers were told.	”Let me transfer you to a specialist who can help.”

Where it shows up

• Flows & KB actions – Selecting builtin-handoff now displays Reason and Pre-handoff utterance fields.
• Functions – Call conv.handoff(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.

Why it matters

• Removes guess-work 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:

   • Ensure your Twilio account is set up and you have the necessary credentials (Account SID, Auth Token).
   • Go to the Telephony section in the Agent Studio.
   • Enter your Twilio credentials to connect your account securely.

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.

Feature	Call 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:

• 30034 - Unregistered Number
• 30035 - Number Still Being Configured