Skip to content

richiectr360/Insurance-call-center

BranchesTags

Repository files navigation

Insurance Claims Voice Agent

A production-ready VoiceAI agent for handling inbound insurance claims support calls. Built using Deepgram Agent API for real-time speech-to-text, text-to-speech, and LLM orchestration, with Supabase for data storage and OpenAI for post-call analysis.

🚀 Live Demo

Deployed on Render:

Call the number above to test the voice agent. Check the endpoints to see real-time metrics and system health.

What This Project Does

This voice agent handles customer service calls for insurance claim status inquiries. When customers call in, the AI agent:

  1. Authenticates callers by phone number and name verification
  2. Retrieves their claim status from the database (approved, pending, or requires documentation)
  3. Answers common FAQ questions (office hours, address, claims process)
  4. Handles escalation requests and emergency situations
  5. Logs every call with summaries and sentiment analysis to the database

The agent uses natural conversation to guide callers through the process, automatically handles errors gracefully, and logs all interactions for analytics and quality monitoring.

Features

  • Real-time Voice Conversations: Powered by Deepgram Agent API (STT + TTS + LLM)
  • Caller Authentication: Phone number lookup with name verification
  • Claim Status Retrieval: Real-time queries from Supabase database
  • FAQ Support: Answers questions about office hours, addresses, and claims process
  • Escalation Handling: Graceful handling of human rep requests and emergency situations
  • Post-Call Logging: Automatic summary generation, sentiment analysis, and database logging
  • Production Features: Retry logic, circuit breakers, rate limiting, structured logging, metrics, and health checks

Architecture Overview

┌─────────────┐
│   Twilio    │ (Telephony)
└──────┬──────┘
       │ WebSocket
       ▼
┌─────────────────┐
│   main.py       │ (WebSocket Server)
│   - Call State  │
│   - Logging     │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│ Deepgram Agent  │ (STT/TTS/LLM)
│      API        │
└──────┬──────────┘
       │
       ├─────────► OpenAI (Post-call: Summary/Sentiment)
       │
       ▼
┌─────────────────┐
│ insurance_      │
│ functions.py    │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│   Supabase      │ (PostgreSQL Database)
│  - customers    │
│  - claims       │
│  - interactions │
└─────────────────┘

Technology Stack:

  • STT/TTS: Deepgram Nova-3 (STT) and Aura-2-Thalia (TTS)
  • LLM: OpenAI GPT-4o-mini (via Deepgram Agent API)
  • Database: Supabase (PostgreSQL)
  • Telephony: Twilio Media Streams
  • Language: Python 3.11+

Prerequisites

Before setting up, ensure you have:

Setup Instructions

1. Clone and Install Dependencies

cd insurance-claims-agent
pip install -r requirements.txt

Or use a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your API keys:

# Required
DEEPGRAM_API_KEY=your_deepgram_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

# Optional (defaults shown in comments)
# PORT=5000
# LOG_LEVEL=INFO
# MAX_RETRIES=3

Where to find credentials:

3. Set Up Supabase Database

  1. Go to your Supabase project: https://supabase.com/dashboard
  2. Navigate to SQL Editor
  3. Open supabase/schema.sql from this project
  4. Copy the entire contents and paste into the SQL Editor
  5. Click Run to execute

This creates three tables:

  • customers - Customer phone numbers and names
  • claims - Insurance claims linked to customers
  • interactions - Call logs with summaries and sentiment

The schema includes sample test data for development.

4. Configure Twilio Media Streams

  1. Log into Twilio Console
  2. Go to Phone Numbers → Manage → Active numbers
  3. Click your phone number
  4. Scroll to Media Streams section
  5. Enable Media Streams
  6. Set WebSocket URL to your server URL:
    • For local development: Use ngrok WebSocket URL (e.g., wss://abc123.ngrok.io) - see "Running Locally" below
    • For production (Render): wss://your-app-name.onrender.com (no /twilio path needed)
  7. Ensure format is set to audio/mulaw
  8. Save

Note: The server handles WebSocket connections at the root path (/), so use just the base URL without any path suffix.

Running the Server

Production Deployment (Render) ✅ Currently Deployed

The application is deployed and live on Render:

Deployment Details:

  • Platform: Render (Free tier - spins down after 15 min inactivity, ~30 sec wake time)
  • Auto-deploy: Enabled (automatically deploys on git push to main branch)
  • Environment variables: Set in Render dashboard

For deployment instructions, see DEPLOYMENT_RENDER.md.

Note: The server uses a unified HTTP/WebSocket server on a single port (Render's PORT env var), making it compatible with platforms like Render that require all traffic on one port.

Local Development with ngrok

For local testing and development, you need to expose your server to the internet so Twilio can connect:

Terminal 1 - Start the server:

python main.py

The server starts on localhost:5000 by default (configurable via PORT env var).

Terminal 2 - Expose with ngrok:

ngrok http 5000

Copy the WebSocket URL from ngrok output (e.g., wss://abc123.ngrok.io) and use it in your Twilio Media Streams configuration (see "Configure Twilio Media Streams" above).

When to use ngrok:

  • Local development and testing
  • Testing changes before deploying to production
  • Debugging issues locally

When not needed:

  • Production deployment (use Render URL directly)
  • Testing the live deployed version (use +1 319 669 8891)

Other Deployment Options

The server is a standard Python WebSocket application. Deploy to any platform that supports WebSocket connections:

  • Railway: Connect your GitHub repo, set environment variables
  • Fly.io: Use fly launch and configure env vars
  • AWS/GCP/Azure: Deploy as a containerized service

Ensure the platform:

  • Supports WebSocket connections
  • Allows inbound connections on your configured port
  • Has environment variables configured
  • Can run Python 3.11+

Health Check and Metrics

The server provides two HTTP endpoints for monitoring (on the same port as WebSocket):

Production (Render):

Local Development:

curl http://localhost:5000/health
curl http://localhost:5000/metrics

Health Check returns:

  • System health status (healthy/degraded/error)
  • Service connectivity (Supabase, OpenAI, Deepgram)
  • Basic metrics (active calls, total calls, total interactions)
  • Version information

Metrics returns:

  • Detailed counters (calls, function calls, API requests, errors)
  • Timing statistics (call duration, database queries, API latencies)
  • Performance percentiles (p50, p95, p99)

These endpoints are publicly accessible and can be used for monitoring and debugging.

Testing

Test the Live Deployment

Call the deployed number: +1 319 669 8891

The agent is live and ready to handle calls. Check the metrics endpoint after calling to see real-time statistics.

Test Phone Numbers (Database)

The schema includes sample test data. Use these phone numbers when the agent asks during a call:

  • John Doe: +15551234567 (or 555-123-4567)
  • Sarah Miller: +15551234568
  • Bob Johnson: +15234567368
  • Alice Williams: +15351145161

Happy Path Test

  1. Call +1 319 669 8891
  2. Agent greets you and asks for your phone number
  3. Provide: +15551234567 (John Doe)
  4. When asked for your name, say: John Doe
  5. Agent retrieves and communicates claim status
  6. Call ends and logs to Supabase
  7. Check https://insurance-claims-agent.onrender.com/metrics to see the call metrics

Error Path Test

  1. Call +1 319 669 8891
  2. Agent asks for phone number
  3. Provide an invalid phone number: +15559999999
  4. Agent should handle gracefully and offer human follow-up
  5. Call ends and logs to Supabase (even failed authentications are logged)

Local Testing

For local testing, you need ngrok running (see "Local Development with ngrok" above):

  1. Start server: python main.py
  2. Start ngrok: ngrok http 5000
  3. Update Twilio WebSocket URL to ngrok URL: wss://abc123.ngrok.io
  4. Call your Twilio number
  5. Test with the same phone numbers listed above

Verify Logging

After a call, verify it was logged:

Option 1: Check Metrics Endpoint Visit https://insurance-claims-agent.onrender.com/metrics and look for:

  • interactions.logged: Should increment after each completed call
  • total_interactions: Total number of calls logged

Option 2: Check Supabase Database Query the interactions table directly:

SELECT * FROM interactions 
ORDER BY created_at DESC 
LIMIT 5;

You should see:

  • call_id: Unique call identifier
  • caller_name: Name if authenticated (NULL if not)
  • phone_number: Phone number used
  • summary: Generated conversation summary (2-3 sentences from OpenAI)
  • sentiment: positive/neutral/negative (analyzed by OpenAI)
  • transcript: Full conversation transcript
  • created_at: Timestamp

Note: Metrics reset when the server restarts (they're in-memory), but Supabase data is permanent.

Project Structure

insurance-claims-agent/
├── main.py                    # Main WebSocket server
├── insurance_functions.py     # Supabase integration functions
├── config.json                # Deepgram Agent API configuration
├── requirements.txt           # Python dependencies
├── .env.example              # Environment variable template
├── .env                       # Your environment variables (not in git)
├── README.md                 # This file
├── utils/                     # Utility modules
│   ├── config.py             # Configuration management
│   ├── logging.py            # Structured logging
│   ├── metrics.py            # Metrics collection
│   ├── retry.py              # Retry logic with backoff
│   ├── circuit_breaker.py    # Circuit breaker pattern
│   └── rate_limiter.py       # Rate limiting
└── supabase/
    └── schema.sql            # Database schema and sample data

Key Components

Call Flow

  1. Greeting: Agent greets caller and asks for phone number
  2. Authentication: Lookup by phone → Verify name → Confirm identity
  3. Claim Status: Retrieve claim from database → Communicate status clearly
  4. FAQ/Escalation: Handle questions or requests for human representative
  5. Call End: Generate summary → Analyze sentiment → Log to database

Function Calls

The agent uses these functions (defined in insurance_functions.py):

  • lookup_caller_by_phone(phone_number): Lookup customer in Supabase
  • get_claim_status(phone_number): Retrieve claim status for authenticated caller
  • log_interaction(...): Log call summary and sentiment (called automatically)

Post-Call Processing

After each call ends:

  • Summary Generation: Uses OpenAI to create a 2-3 sentence summary of the conversation
  • Sentiment Analysis: Uses OpenAI to determine overall sentiment (positive/neutral/negative)
  • Database Logging: Stores all data in Supabase interactions table

Configuration

Environment Variables

All configuration is done via environment variables. See .env.example for all available options.

Required:

  • DEEPGRAM_API_KEY: Deepgram API key for voice AI
  • OPENAI_API_KEY: OpenAI API key for summaries/sentiment
  • SUPABASE_URL: Your Supabase project URL
  • SUPABASE_SERVICE_ROLE_KEY: Supabase service role key

Optional (with defaults):

  • PORT: Server port (default: 5000, Render sets this automatically)
  • HOST: Server host (default: 0.0.0.0)
  • LOG_LEVEL: Logging level (default: INFO)
  • MAX_RETRIES: Retry attempts for failed operations (default: 3)

Note: When deploying to Render, the PORT environment variable is automatically set by Render - you don't need to configure it manually.

Deepgram Configuration

The agent's behavior and prompts are configured in config.json. This file contains:

  • Audio settings (encoding, sample rate)
  • LLM model and prompts
  • Function definitions
  • Greeting message

Advanced Features

This project includes production-ready features:

  • Structured Logging: JSON-formatted logs for easy parsing and aggregation
  • Retry Logic: Automatic retries with exponential backoff for transient failures
  • Circuit Breaker: Prevents cascading failures when external services are down
  • Rate Limiting: Protects against API rate limit violations
  • Connection Pooling: Efficient database connection management
  • Metrics Collection: Real-time performance and usage metrics
  • Health Checks: HTTP endpoints for monitoring and deployment platforms

Troubleshooting

Port Already in Use

If port 5000 is in use:

PORT=5001 python main.py

Database Connection Issues

  • Verify SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env
  • Ensure schema has been run in Supabase SQL Editor
  • Check Supabase project is active

Import Errors

Ensure all dependencies are installed:

pip install -r requirements.txt

Configuration Validation Errors

The server validates required environment variables on startup. If missing, you'll see an error listing what's required.

License

MIT License

Acknowledgments

Built for the Observe.AI Take-Home Assessment. Uses patterns and inspiration from:

  • Deepgram Voice Agent examples
  • Insurance call center AI implementations

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages