> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Five9

> Connect your PolyAI agent to Five9 through a SIP trunk for call routing and handoffs.

Connect PolyAI to Five9 through a shared SIP trunk for call routing and live-agent handoff. This guide covers setup, routing methods, and transfer configuration.

## 1: Integrate with the shared Five9 and PolyAI SIP trunk

Five9 uses a multi-tenant SIP trunk to connect with PolyAI. Contact your [Five9 account manager](https://www.five9.com/) to configure your environment to connect to this SIP trunk and route calls to PolyAI.

## 2: Five9 to PolyAI routing methods

#### Authentication token

PolyAI provides an authentication token included in the SIP INVITE message under the X-header (`X-PolyAi-Auth-Token`). This token identifies and distinguishes traffic for accurate agent routing.

#### Dialed extension

Five9 and PolyAI agree on unique extension numbers for routing calls. This method offers flexibility and scalability, especially for clients managing multiple PolyAI agents.

## 3: PolyAI to Five9 transfer methods

#### SIP BYE with custom headers

When PolyAI is unable to contain a call, it sends a SIP BYE message with custom headers to indicate the status of the call. This method is simple and suitable for scenarios with limited metadata requirements.

Key headers include:

* `X-contained`: Indicates whether the call was contained by PolyAI. (`true` or `false`)
* `X-destination`: Specifies where to transfer the call if it was not contained. Values are determined during deployment.

> **Warning**
>
> Five9 supports up to 10 custom headers. Additional requirements should be discussed with PolyAI during deployment.

#### PolyAI Handoff API

For cases requiring detailed metadata, PolyAI provides a [Handoff API](/api-reference/runtime-data/handoff-api/overview) to return larger data payloads. This method involves:

1. PolyAI sends a SIP BYE message to Five9 to indicate the agent call leg is complete.
2. Five9 uses scripting to call the PolyAI Handoff API, using the Five9 session ID as the `shared_id` parameter to retrieve data.
3. The API response includes:
   * `contained`: Indicates whether the call was contained. (`true` or `false`)
   * `destination`: Specifies the transfer destination if the call was not contained.

**Benefits**:

* No size limit on the API response, enabling detailed metadata transfer.
* Flexible for advanced routing decisions.

**Considerations**:

* Ensure error handling in the Five9 scripting to manage API response issues.

### Example API integration

```python
import requests

def call_handoff_api(api_url, api_key, shared_id):
    """
    Calls the PolyAI Handoff API to retrieve call metadata.

    :param api_url: Handoff API URL
    :param api_key: PolyAI API key
    :param shared_id: Five9 session ID used for the call
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    payload = {"shared_id": shared_id}

    response = requests.post(api_url, headers=headers, json=payload)
    response_data = response.json()

    if response.status_code == 200:
        return response_data
    else:
        raise Exception(f"API Error: {response.status_code} - {response.text}")

# Example usage
api_url = "https://api.{region}.platform.polyai.app/handoff"  # Replace {region} with us-1, uk-1, or euw-1
api_key = "your_polyai_api_key"
shared_id = "five9_session_id"

data = call_handoff_api(api_url, api_key, shared_id)
print("Call metadata:", data)
```