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

The Call Handoffs section allows you to define destinations that calls can be routed to during conversations. This is useful for scenarios where the assistant cannot handle a query and needs to transfer the call to a specific live agent or team.

​
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:
    • Handoff destination name: Enter a descriptive name (e.g., “Front desk”).
    • Extension / Number: Provide the phone number or extension to route the call.
    • Description: Add a note about when to use this handoff (e.g., “When the call needs help with a broader topic”).
  4. Click Add to save the destination.

​
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 assistant by setting the Webhook URL in your Twilio console. For 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”).

​
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 museum assistant might have a handoff destination called “School visits” to transfer calls related to group bookings or educational inquiries.

​
Best practices for call handoffs

  • Clear descriptions: Use descriptive names and notes to ensure accurate call routing.
  • Fallback options: Set a default handoff destination as a fallback to handle any unclassified transfers.
  • Test routes: Regularly test handoff destinations to confirm that they function correctly.
  • Secure Twilio credentials: Ensure your Twilio credentials are stored securely and have restricted access to prevent unauthorized usage.

By leveraging the Call Handoffs section and integrating Twilio effectively, you can streamline call routing and provide a seamless experience for both your users and live agents.

RulesOverview