Five9

PolyAI integrates with Five9 via 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 to configure your environment to connect to this SIP trunk and route calls to PolyAI.

2: Five9 to PolyAI routing methods

Authentication token
Dialed extension

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.

3: PolyAI to Five9 transfer methods

SIP BYE with custom headers
PolyAI Handoff API

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.

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

For cases requiring detailed metadata, PolyAI provides a Handoff API to return larger data payloads. This method involves:

PolyAI sends a SIP BYE message to Five9 to indicate the agent call leg is complete.
Five9 uses scripting to call the PolyAI Handoff API, using the Five9 session ID as the shared_id parameter to retrieve data.
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

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)

Integrations

Voice

Reservations & hospitality

CRM & customer support

Healthcare

Payments

Data & utilities

1: Integrate with the shared Five9 and PolyAI SIP trunk

2: Five9 to PolyAI routing methods

3: PolyAI to Five9 transfer methods

Example API integration

Integrations

Voice

Reservations & hospitality

CRM & customer support

Healthcare

Payments

Data & utilities

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

​2: Five9 to PolyAI routing methods

​3: PolyAI to Five9 transfer methods

​Example API integration

1: Integrate with the shared Five9 and PolyAI SIP trunk

2: Five9 to PolyAI routing methods

3: PolyAI to Five9 transfer methods

Example API integration