Skip to main content

Advanced Features

Core Usage​

Keep your integration simple and reliable. The primary flow is:

# 1) Start a session
session_id = whispey.start_session(session)

# ... run your LiveKit agent ...

# 2) Export data on shutdown only
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Session Metadata​

Enrich your analytics with detailed session information.

Basic Metadata​

session_id = whispey.start_session(
    session=your_livekit_session,
    phone_number="+1234567890",
    customer_name="John Doe",
    conversation_type="customer_support",
    metadata={
        "department": "technical_support",
        "priority": "high",
        "language": "en",
        "tags": ["escalation", "urgent"]
    }
)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Advanced Metadata​

metadata = {
    # User information
    "user_id": "user_12345",
    "user_type": "premium",
    "account_tier": "enterprise",
    
    # Session context
    "session_type": "voice_call",
    "channel": "phone",
    "device_type": "mobile",
    
    # Business context
    "product": "mobile_app",
    "feature": "login_support",
    "campaign": "q4_2024_support",
    
    # Technical context
    "agent_version": "2.1.0",
    "model_config": "gpt-4o-mini",
    "region": "us-east-1",
    
    # Custom fields
    "custom_field_1": "value_1",
    "custom_field_2": "value_2"
}

session_id = whispey.start_session(
    session=your_livekit_session,
    metadata=metadata
)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Multi-Agent Support​

Track and compare performance across multiple agents.

Agent Comparison​

# Initialize multiple agents and compare basic outcomes
agents = {
    "support_agent": LivekitObserve(agent_id="support-001", apikey="your-api-key"),
    "sales_agent": LivekitObserve(agent_id="sales-001", apikey="your-api-key"),
    "billing_agent": LivekitObserve(agent_id="billing-001", apikey="your-api-key")
}

# Start sessions for comparison
sessions = {}
for name, agent in agents.items():
    sessions[name] = agent.start_session(session=your_livekit_session)
    
    # Set up shutdown callback for each agent
    async def create_shutdown_callback(agent_name, session_id):
        async def shutdown():
            await agents[agent_name].export(session_id)
        return shutdown
    
    ctx.add_shutdown_callback(create_shutdown_callback(name, sessions[name]))

# ... run conversations ...

Bug Reporting System​

Enable automatic bug detection and reporting in your conversations.

Basic Bug Reporting​

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True
)

session_id = whispey.start_session(session=your_livekit_session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Custom Bug Reporting​

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config={
        "bug_start_command": ["report issue", "there's a problem"],
        "bug_end_command": ["issue resolved", "problem fixed"],
        "response": "Please describe the issue.",
        "collection_prompt": "Got it, anything else?",
        "continuation_prefix": "So, as I was saying, ",
        "fallback_message": "Let me continue our conversation."
    }
)

session_id = whispey.start_session(session=your_livekit_session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

OpenTelemetry Integration​

Enable detailed telemetry collection for advanced monitoring.

Basic OpenTelemetry​

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    enable_otel=True  # Enable telemetry capture
)

session_id = whispey.start_session(session=your_livekit_session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Telemetry Data​

When enabled, OpenTelemetry captures:

  • STT Spans: Audio processing with duration and model info
  • LLM Spans: Token usage, latency, and request details
  • TTS Spans: Character counts, synthesis timing
  • Tool Spans: Function executions with performance metrics

Export Options​

Important: Export should only happen on shutdown, not during the session.

Basic Export on Shutdown​

# Set up shutdown callback
async def whispey_shutdown():
    result = await whispey.export(session_id)
    
    if result.get("success"):
        print("Successfully exported to Whispey Voice Analytics!")
    else:
        print(f"Export failed: {result.get('error')}")

ctx.add_shutdown_callback(whispey_shutdown)

Export with Recording URL on Shutdown​

async def whispey_shutdown():
    result = await whispey.export(
        session_id,
        recording_url="https://example.com/recording.mp3"  # Optional: Add recording URL
    )
    
    if result.get("success"):
        print("Successfully exported to Whispey Voice Analytics!")
    else:
        print(f"Export failed: {result.get('error')}")

ctx.add_shutdown_callback(whispey_shutdown)

Available Configuration Options​

LivekitObserve Constructor​

LivekitObserve(
    agent_id: str,                    # Required: Your agent ID from dashboard
    apikey: str = None,              # Optional: API key (can use env var)
    host_url: str = None,            # Optional: Custom API endpoint
    bug_reports_enable: bool = False,  # Optional: Bug reporting configuration
    bug_reports_config: dict = None,  # Optional: Bug reporting configuration
    enable_otel: bool = False        # Optional: Enable OpenTelemetry
)

start_session Method​

session_id = whispey.start_session(
    session,                    # Required: LiveKit session object
    phone_number: str = None,   # Optional: Customer phone number
    customer_name: str = None,  # Optional: Customer name
    conversation_type: str = None,  # Optional: Type of conversation
    metadata: dict = None       # Optional: Additional metadata
)

export Method​

result = await whispey.export(
    session_id,                 # Required: Session ID from start_session
    recording_url: str = None,  # Optional: Recording URL
)

Next Steps​