> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/integrations/voice/twilio",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Twilio

> Connect your PolyAI agent to Twilio Flex for voice automation and handoffs.

<Note>
  For basic Twilio setup, see the [Configure > Numbers > Twilio guide](/telephony/twilio/introduction).
</Note>

Route calls to PolyAI through [Twilio Flex](https://www.twilio.com/en-us/flex/use-cases/contact-center) and manage [handoffs](/call-handoff/introduction) to live agents through SIP or Twilio Studio. Handle complex customer queries automatically or escalate to human agents.

<CardGroup cols={3}>
  <Card title="Set up connector" icon="square-1">
    Create a [PolyAI Connector](#set-up-connector) and retrieve your Connector Token.
  </Card>

  <Card title="Configure routing" icon="square-2">
    Use **[TwiML or Twilio Studio](#configure-routing)** to route calls to PolyAI.
  </Card>

  <Card title="Handle handoffs" icon="square-3">
    Manage live-agent handoffs with the [PolyAI Handoff API](#handle-handoffs).
  </Card>
</CardGroup>

PolyAI uses a [media stream](https://www.twilio.com/docs/voice/media-streams)
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](https://www.twilio.com/docs/flex/developer/ui).
* **Routing**: Supports Twilio Studio flows and programmable routing using [TwiML syntax](https://www.twilio.com/docs/glossary/what-is-twilio-markup-language-twiml).

## 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:

```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
<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](https://www.twilio.com/docs/studio/widget-library/http-request) to retrieve PolyAI handoff context using an API.
3. Use a [**Send To Flex** widget](https://www.twilio.com/docs/studio/widget-library/send-flex) 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](/api-reference/handoff/endpoint/get-handoff).
3. **Flex display**: The data is passed to Twilio Flex, where live agents can view it in the Flex UI.

### Example Twilio Function

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}

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);
  }
};
```

## Related documentation

* **[Configure > Numbers > Twilio](/telephony/twilio/introduction)** - Basic Twilio phone number and SMS setup
* **[Call Handoffs](/call-handoff/introduction)** - Configure handoff destinations
* **[Handoff API](/api-reference/handoff/introduction)** - Retrieve handoff context programmatically

## Twilio resources

* [Twilio Flex Documentation](https://www.twilio.com/docs/flex)
* [Twilio Studio](https://www.twilio.com/docs/studio)
* [Twilio Flex Plugin Quickstart](https://www.twilio.com/docs/flex/quickstart/getting-started-plugin)