Five9

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.

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

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.

For cases requiring detailed metadata, PolyAI provides a Handoff API 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

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.poly.ai/handoff"
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)