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

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

​
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).
    • Navigate 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.

Troubleshooting: If your messages fail to send, check the Twilio logs for these error codes: