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

​

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.

​

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