> ## 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/sip/five9",
  "feedback": "Description of the issue"
}
```

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

</AgentInstructions>

# 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

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## 3: PolyAI to Five9 transfer methods

<Tabs>
  <Tab title="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. </Warning>
  </Tab>

  <Tab title="PolyAI Handoff API">
    For cases requiring detailed metadata, PolyAI provides a [Handoff API](/api-reference/handoff/introduction) 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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)
    ```
  </Tab>
</Tabs>