Skip to main content

Configuration

Required Environment Variables​

VariableDescriptionWhere to Get
WHISPEY_API_KEYYour Whispey API authentication keyDashboard → API Keys

Agent Configuration​

Replace "your-agent-id-from-dashboard" with your actual Agent ID from the Whispey dashboard in your workspace.

whispey = LivekitObserve(
    agent_id="2a72948a-094d-4a13-baf7-e033a5cdeb22",  # Your actual Agent ID
    apikey=os.getenv("WHISPEY_API_KEY")
)

Advanced Configuration​

Session Metadata​

You can add additional metadata to your sessions for better analytics:

session_id = whispey.start_session(
    session=your_livekit_session,
    phone_number="+1234567890",        # Customer phone number
    customer_name="John Doe",          # Customer name
    conversation_type="voice_call",    # Type of conversation
    metadata={
        "department": "support",
        "priority": "high",
        "language": "en"
    }
)

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

ctx.add_shutdown_callback(whispey_shutdown)

Bug Reporting Configuration​

Enable automatic bug detection and 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)

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

ctx.add_shutdown_callback(whispey_shutdown)

OpenTelemetry Configuration​

Enable detailed telemetry collection:

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

session_id = whispey.start_session(session)

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

ctx.add_shutdown_callback(whispey_shutdown)

Custom API Endpoint​

Use a custom API endpoint if needed:

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    host_url="https://api.whispey.xyz"  # Custom API endpoint
)

session_id = whispey.start_session(session)

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

ctx.add_shutdown_callback(whispey_shutdown)

Environment Setup​

For production environments, ensure proper environment variable management:

# Development
export WHISPEY_API_KEY="your_api_key_here"

# Production (use your deployment platform's secrets management)
# Heroku, Vercel, AWS, etc.

Logging Configuration​

Enable detailed logging for debugging:

import logging

# Set logging level
logging.basicConfig(level=logging.INFO)

# Your Whispey code here - you'll see detailed logs

Security Best Practices​

  1. Never commit API keys to version control
  2. Use environment variables for sensitive data
  3. Rotate API keys regularly
  4. Monitor usage through the dashboard
  5. Implement proper error handling for failed exports

Troubleshooting​

Common Issues​

  1. "Session not found" Error

    # Ensure session_id is stored correctly
    session_id = whispey.start_session(session)
    print(f"Session ID: {session_id}")  # Save this for later use

  2. API Authentication Error

    # Check your .env file
    echo $WHISPEY_API_KEY

    # Ensure API key is set in environment
    export WHISPEY_API_KEY="your_api_key_here"

  3. Export Failures

    # Always handle export errors gracefully
    async def whispey_shutdown():
        try:
            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')}")
        except Exception as e:
            print(f"Export error: {e}")

    ctx.add_shutdown_callback(whispey_shutdown)

Next Steps​