Configuration

Required Environment Variables

Variable	Description	Where to Get
`WHISPEY_API_KEY`	Your Whispey API authentication key	Dashboard → 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

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

Troubleshooting

Common Issues

"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

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"

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

Learn about Advanced Features
Check out Examples for real-world usage
Visit our GitHub Examples Repository

Configuration

On this page