five9-stats 0.1.0

Python client library for Five9 Statistics APIs

Five9 Statistics API Client Library

A Python client library for the Five9 Statistics APIs, providing asynchronous access to both the Interval Statistics API and the Real-time Stats Snapshot API.

Features

• Asynchronous API clients using aiohttp
• Pydantic models for request and response data
• Support for both Interval Statistics API and Real-time Stats Snapshot API
• Automatic retry mechanism for rate limiting and service unavailability
• Comprehensive error handling

Installation

pip install five9-stats

Or install from source:

git clone https://github.com/james-smart/five9-stats.git
cd five9-stats
pip install -e .

Requirements

• Python 3.7+
• aiohttp
• pydantic

Usage

See the included exmple.py script for a complete example of how to use the library.

Interval Statistics API

The Interval Statistics API provides historical statistics for domains, agents, campaigns, and ACD.

import asyncio
from five9_stats.api.interval import IntervalStatsClient

async def main():
    # Initialize the client
    client = IntervalStatsClient(
        username="your_username",
        password="your_password",
        base_url="https://api.prod.us.five9.net"  # Optional, defaults to US production
    )
    
    # Use the client as an async context manager
    async with client:
        # Get statistics metadata
        metadata = await client.get_statistics_metadata(domain_id="your_domain_id")
        print(f"Available statistics types: {[m.statistics_type for m in metadata.items]}")
        
        # Get agent statistics
        agent_stats = await client.get_agent_statistics(
            domain_id="your_domain_id",
            media_types="VOICE,CHAT,EMAIL",
            time_period="LAST_15_MINUTES"
        )
        
        # Print agent statistics
        for agent in agent_stats.data:
            print(f"Agent ID: {agent.id}")
            print(f"Total calls handled: {agent.total_calls_handled}")
            print(f"Total chats handled: {agent.total_chats_handled}")
            print(f"Total emails handled: {agent.total_emails_handled}")
            print("---")

# Run the async function
asyncio.run(main())

Real-time Stats Snapshot API

The Real-time Stats Snapshot API provides real-time statistics for domains, agents, interactions, campaigns, and utilization thresholds.

import asyncio
from five9_stats.api.snapshot import SnapshotStatsClient

async def main():
    # Initialize the client
    client = SnapshotStatsClient(
        username="your_username",
        password="your_password",
        base_url="https://api.prod.us.five9.net"  # Optional, defaults to US production
    )
    
    # Use the client as an async context manager
    async with client:
        # Get ACD status
        acd_status = await client.get_acd_status(
            domain_id="your_domain_id",
            media_types="VOICE,CHAT,EMAIL"
        )
        
        # Print ACD status
        for skill in acd_status.data:
            print(f"Skill ID: {skill.id}")
            print(f"Active calls: {skill.active_calls}")
            print(f"Agents active: {skill.agents_active}")
            print(f"Agents on call: {skill.agents_on_call}")
            print(f"Calls in queue: {skill.calls_in_queue}")
            print("---")
        
        # Get agent state
        agent_state = await client.get_agent_state(
            domain_id="your_domain_id",
            media_types="VOICE,CHAT,EMAIL"
        )
        
        # Print agent state
        for agent in agent_state.data:
            print(f"Agent ID: {agent.id}")
            print(f"Presence state: {agent.presence_state}")
            print(f"Voice interaction state: {agent.voice_interaction_state}")
            print(f"Chat interaction state: {agent.chat_interaction_state}")
            print(f"Email interaction state: {agent.email_interaction_state}")
            print("---")

# Run the async function
asyncio.run(main())

Error Handling

The library provides comprehensive error handling for API errors:

import asyncio
from five9_stats.api.interval import IntervalStatsClient

async def main():
    client = IntervalStatsClient(username="your_username", password="your_password")
    
    async with client:
        try:
            # Try to get statistics for a non-existent domain
            stats = await client.get_agent_statistics(domain_id="invalid_domain_id")
        except ValueError as e:
            print(f"API error: {e}")

asyncio.run(main())

Advanced Usage

Custom Retry Logic

You can customize the retry behavior:

client = IntervalStatsClient(
    username="your_username",
    password="your_password",
    max_retries=5,       # Maximum number of retries
    retry_delay=2        # Initial delay between retries in seconds (will use exponential backoff)
)

Using Different Regional Endpoints

Five9 provides different regional endpoints:

# US production
client = IntervalStatsClient(
    username="your_username",
    password="your_password",
    base_url="https://api.prod.us.five9.net"
)

# EU production
client = IntervalStatsClient(
    username="your_username",
    password="your_password",
    base_url="https://api.prod.eu.five9.net"
)

# CA production
client = IntervalStatsClient(
    username="your_username",
    password="your_password",
    base_url="https://api.prod.ca.five9.net"
)

License

MIT