Skip to main content
This page covers the advanced Twilio Flex integration for contact centers. For basic Twilio phone number and SMS setup, see the Telephony > Twilio guide.
The PolyAI integration for Twilio Flex for contact centers routes incoming customer calls to PolyA’s voice agents using the Twilio telephony system, and then manages handoff if they need to be handed on to a live agent. If handoff is needed, the integration transfers the call and accompanying data to Twilio Flex for human handling. All interactions are managed through SIP or a no-code Twilio Studio workflow, and are logged in the Twilio UI.

Set up connector

Create a PolyAI Connector and retrieve your Connector Token using the API.

Install Twilio addon

Link your PolyAI Connector Token to Twilio.

Configure routing

Use TwiML or Twilio Studio to route calls to PolyAI.

Handle handoffs

Manage live-agent handoffs with the PolyAI Handoff API.
PolyAI is live on the Twilio Marketplace and 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, start by creating 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 support@poly.ai 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.

​
Install Twilio addon

After obtaining the Connector Token, install the PolyAI Connector Addon in Twilio:
  1. Log in to your Twilio account.
  2. Go to the Twilio Marketplace and search for “PolyAI Connector.”
  3. Install the addon and paste your Connector Token into the required field.
  4. Save changes and verify the connection.

​
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