Whispey SDK

Professional Voice Analytics for AI Agents

Monitor, analyze, and gain insights from your AI voice agent conversations with Whispey's advanced voice analytics platform.

🚀 Quick Start

Installation

pip install whispey

Get Your Credentials

1. Sign up at Whispey Voice Analytics Dashboard
2. Get your Agent ID from the dashboard
3. Generate your API Key from your workspace

Environment Setup

Create a .env file in your project root:

# Whispey Voice Analytics
WHISPEY_API_KEY=your_whispey_api_key_here

🔧 Configuration

Required Environment Variables

Agent Configuration

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

pype = LivekitObserve(
    agent_id="2a72948a-094d-4a13-baf7-e033a5cdeb22"  # Your actual Agent ID
)

📖 Complete Implementation

Here's a complete example of how to integrate Whispey Observe into your LiveKit voice agent:

from dotenv import load_dotenv
from livekit import agents
from livekit.agents import AgentSession, Agent, RoomInputOptions
from livekit.plugins import (
    openai,
    deepgram,
    noise_cancellation,
    silero,
    elevenlabs,
)
from livekit.plugins.turn_detector.multilingual import MultilingualModel
from whispey import LivekitObserve

import base64
import os

# Load environment variables
load_dotenv()

# 🎙️ Initialize Whispey with your Agent ID from the dashboard
pype = LivekitObserve(
    agent_id="your-agent-id-from-dashboard"  # Get this from https://whispey.xyz/

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(instructions="You are a helpful voice AI assistant.")

async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()
        
    # Configure your AI agent session
    session = AgentSession(
        stt=deepgram.STT(model="nova-3", language="multi"),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=elevenlabs.TTS(
            voice_id="H8bdWZHK2OgZwTN7ponr",
            model="eleven_flash_v2_5",
            language="hi",  # Adjust language as needed
            voice_settings=elevenlabs.VoiceSettings(
                similarity_boost=1,
                stability=0.7,
                style=0.7,
                use_speaker_boost=False,
                speed=1.1
            )
        ),
        vad=silero.VAD.load(),
        turn_detection=MultilingualModel(),
    )
    
    # 🚀 Start Whispey Voice Analytics
    session_id = pype.start_session(
        session,
        phone_number="+1234567890",     # Optional: Customer phone number
        customer_name="John Doe",       # Optional: Customer name
        conversation_type="voice_call"  # Optional: Type of conversation
    )
    
    print(f"🎙️ Whispey Analytics started for session: {session_id}")

    # 📤 Export analytics data when session ends
    async def whispey_shutdown():
        try:
            result = await whispey.export(
                session_id,
                recording_url=""  # Optional: Add recording URL if available
            )
            
            if result.get("success"):
                print("✅ Successfully exported to Whispey Voice Analytics!")
                print(f"📊 Log ID: {result.get('data', {}).get('log_id')}")
            else:
                print(f"❌ Export failed: {result.get('error')}")
                
        except Exception as e:
            print(f"💥 Export error: {e}")

    # Register cleanup callback
    ctx.add_shutdown_callback(whispey_shutdown)

    # Start the agent session
    await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_input_options=RoomInputOptions(
            noise_cancellation=noise_cancellation.BVC(), 
        ),
    )

    # Generate initial greeting
    await session.generate_reply(
        instructions="Greet the user and offer your assistance."
    )

if __name__ == "__main__":
    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))

📊 Features

Automatic Metrics Collection

• 🎙️ Speech-to-Text (STT): Audio duration, processing time
• 🧠 Large Language Model (LLM): Token usage, response time, TTFT
• 🗣️ Text-to-Speech (TTS): Character count, audio duration, TTFB
• 👂 Voice Activity Detection (VAD): Voice detection metrics
• ⏱️ End of Utterance (EOU): Turn-taking timing

Conversation Analytics

• 📝 Full Transcript: Complete conversation history with timestamps
• 🔄 Turn Tracking: User and agent turns with associated metrics
• 📈 Performance Insights: Response times, token usage, audio quality
• 🎯 Success Metrics: Call completion, lesson progress, handoff detection

📈 Dashboard Integration

Once your data is exported, view detailed analytics at: Whispey Voice Analytics Dashboard

Available Analytics:

• 📊 Call Performance: Response times, success rates
• 🎙️ Voice Quality: Audio metrics, clarity scores
• 💬 Conversation Flow: Turn analysis, interruption patterns
• 📈 Usage Statistics: Token consumption, API costs
• 🎯 Business Metrics: Conversion rates, customer satisfaction

🛠️ Troubleshooting

Common Issues

1. "Session not found" Error

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

3. 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"

Debug Mode

Enable verbose logging:

import logging
logging.basicConfig(level=logging.INFO)

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

📝 Requirements

• Python >= 3.8
• LiveKit Agents >= 1.2.2
• Active Whispey account with valid API key

🤝 Support

• Dashboard: https://whispey.xyz/
• Email: deepesh@pypeai.com
• Issues: GitHub Issues

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ by Whispey Voice Analytics

Transform your voice agents with professional analytics and insights.