Skip to main content
For basic Twilio setup, see the Configure > Numbers > Twilio guide.
Route calls to PolyAI through Twilio Flex and manage handoffs to live agents through SIP or Twilio Studio. Handle complex customer queries automatically or escalate to human agents.

Set up connector

Create a PolyAI Connector and retrieve your Connector Token.

Configure routing

Use TwiML or Twilio Studio to route calls to PolyAI.

Handle handoffs

Manage live-agent handoffs with the PolyAI Handoff API.
PolyAI uses a media stream connector implementation.

​
Capabilities

  • Automated call handling: Twilio routes incoming calls to PolyAI virtual agents, where customer queries are resolved, or additional data is captured for live-agent handoffs.
  • Live-agent handoffs: The PolyAI virtual agent passes contextual data from PolyAI to Twilio Flex, to be displayed in the Flex UI.
  • Routing: Supports Twilio Studio flows and programmable routing using TwiML syntax.

​
Set up connector

To integrate PolyAI with Twilio, create a PolyAI Connector. The connector links Twilio with your PolyAI project configuration.

​
Request connector setup

Connector setup is managed by PolyAI. Contact your account manager or PolyAI representative to request a connector for your Twilio integration. Provide the following information:
  • Friendly name: A descriptive name for your connector
  • Account ID: Your PolyAI account identifier
  • Project ID: Your PolyAI project identifier
  • Client environment: live, pre-release, or sandbox
  • Variant ID: (if applicable)
  • Language codes: ASR and TTS language codes (e.g., en-GB, en-US)

​
Outputs

PolyAI will provide:
  1. Connector ID: Used for debugging configurations.
  2. Connector Token: Required for linking the PolyAI Connector in Twilio.

​
Mapping notes

Each Twilio Connector maps directly to:
  • A PolyAI Connector.
  • A PolyAI project configuration.
To manage multiple environments (e.g., Sandbox and Production), request separate connectors for each.

​
Configure routing

Twilio offers two routing methods: TwiML and Twilio Studio.

​
TwiML syntax

Define your Twilio flow with the <Connect> tag: 
<Response>
  <Say>Connecting your call...</Say>
  <Connect connectorId="[Your Connector ID]" />
</Response>

​
Twilio Studio flow

  1. Open Twilio Studio.
  2. Add a Make HTTP Request widget to retrieve PolyAI handoff context using an API.
  3. Use a Send To Flex widget to route calls to agents with the retrieved context.
  4. Save and test the flow.

​
Handle handoffs

PolyAI provides detailed call context for live-agent handoffs:
  1. Store handoff data: PolyAI captures customer information in the context.state.handoff object.
  2. API retrieval: Twilio Functions fetch this data using the PolyAI Handoff API.
  3. Flex display: The data is passed to Twilio Flex, where live agents can view it in the Flex UI.

​
Example Twilio Function


const axios = require('axios');

exports.handler = async (context, event, callback) => {
  try {
    const config = {
      headers: { "x-api-key": "<your-polyai-api-key>" }
    };
    const response = await axios.get(
      `https://api.polyai.app/v1/handoff_state?id=${event.call_sid}`,
      config
    );
    callback(null, response.data);
  } catch (error) {
    console.error(error);
    callback(error);
  }
};

​
Twilio resources

Last modified on April 20, 2026