Installation

System Requirements

Before installing the AI Voice Testing Platform, ensure your system meets these requirements:

Python: 3.8 or higher
Operating System: Linux, macOS, or Windows
Memory: 512 MB RAM minimum (1 GB recommended)
Network: Internet connection for API calls to OpenAI and ElevenLabs

Installation Methods

Method 1: Standard Installation (Recommended)

This method uses Python’s built-in virtual environment for dependency isolation.

Clone or download the repository

If you have the source code in a directory, navigate to it:

cd /path/to/ai-voice-testing-platform

Create a virtual environment

Create an isolated Python environment:

python -m venv .venv

Or use python3 if your system has both Python 2 and 3:

python3 -m venv .venv

This creates a .venv directory containing an isolated Python installation.

Activate the virtual environment

source .venv/bin/activate

After activation, your terminal prompt should show (.venv).

On Windows PowerShell, you may need to enable script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Install dependencies

Install all required packages from requirements.txt:

pip install -r requirements.txt

This installs:

Package	Version	Purpose
`flask`	3.0.0	Web framework for API and UI
`elevenlabs`	1.14.0	ElevenLabs SDK for voice synthesis
`python-dotenv`	1.0.0	Environment variable management
`openai`	1.55.0	OpenAI SDK for GPT-4o-mini chat

Verify installation

Check that all packages installed correctly:

pip list

You should see flask, elevenlabs, python-dotenv, and openai in the output.

Method 2: System-Wide Installation (Not Recommended)

You can install dependencies globally without a virtual environment:

pip install -r requirements.txt

System-wide installation may cause dependency conflicts with other Python projects. Always prefer virtual environments for isolation.

Configuration

Environment Variables

The application uses environment variables for sensitive configuration. These are loaded via python-dotenv in app.py:15.

Create your .env file

Copy the example file:

cp .env.example .env

The .env.example file contains all required variables with placeholder values.

Configure required variables

Edit .env and set these required values:

.env

# Flask Configuration
FLASK_SECRET_KEY=your-secret-key-here

# API Keys
ELEVENLABS_API_KEY=your-elevenlabs-api-key
OPENAI_API_KEY=your-openai-api-key

# ElevenLabs Conversational AI (for phone calls)
ELEVENLABS_AGENT_ID=your-agent-id
ELEVENLABS_AGENT_PHONE_NUMBER_ID=your-phone-number-id

Variable Reference

FLASK_SECRET_KEY (Required)

Purpose: Encrypts Flask session cookies to protect user data. Usage: app.py:18 Generation:

python -c "import secrets; print(secrets.token_hex(32))"

Default: "dev-secret-change-in-production" (only for development)

Never use the default secret key in production. Generate a cryptographically secure random value.

OPENAI_API_KEY (Required for chat)

Purpose: Authenticates requests to OpenAI for GPT-4o-mini chat completions. Usage: app.py:198, app.py:203 Model: gpt-4o-mini (configured in app.py:205) Get your key: OpenAI Platform Fallback: If not set, the chat endpoint returns a placeholder message instead of failing.

ELEVENLABS_API_KEY (Required for voice)

Purpose: Authenticates requests to ElevenLabs for text-to-speech and phone calls. Usage: app.py:28, app.py:96, app.py:106 Voice ID: JBFqnCBsd6RMkjVDRZzb (George voice, configured in app.py:134) Model: eleven_turbo_v2_5 (configured in app.py:135) Get your key: ElevenLabs Dashboard

ELEVENLABS_AGENT_ID (Required for phone calls)

Purpose: Specifies which ElevenLabs Conversational AI agent to use for outbound calls. Usage: app.py:242, app.py:248 Setup:

Create a Conversational AI agent in ElevenLabs
Enable prompt overrides on the agent
Copy the agent ID from the dashboard

Prompt overrides must be enabled for the app to inject business descriptions at call time via conversation_config_override (app.py:75-83).

ELEVENLABS_AGENT_PHONE_NUMBER_ID (Required for phone calls)

Purpose: Specifies which phone number to use as the caller ID for outbound calls. Usage: app.py:242, app.py:249 Setup:

Connect a Twilio phone number in ElevenLabs
Copy the phone number ID from the ElevenLabs dashboard

Endpoint: The app uses ElevenLabs’ /v1/convai/twilio/outbound-call endpoint (app.py:258)

ELEVENLABS_API_BASE (Optional)

Purpose: Override the default ElevenLabs API base URL. Default: https://api.elevenlabs.io Usage: app.py:20 Use case: Testing against a different ElevenLabs environment or proxy.

Running the Application

Development Mode

Start the Flask development server with debug mode enabled:

python app.py

The server starts on http://localhost:5000 with:

Debug mode: Enabled (app.py:277)
Auto-reload: Changes to app.py trigger automatic restart
Detailed errors: Full stack traces in the browser

Never run debug mode in production. It exposes sensitive information and allows arbitrary code execution.

Production Mode

For production deployments, use a WSGI server like Gunicorn:

Install Gunicorn

pip install gunicorn

Run with Gunicorn

gunicorn -w 4 -b 0.0.0.0:5000 app:app

Flags:

-w 4: Use 4 worker processes
-b 0.0.0.0:5000: Bind to all interfaces on port 5000
app:app: Import app object from app.py

Use a reverse proxy

Configure Nginx or Apache to proxy requests to Gunicorn:

nginx.conf

server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Custom Port

To run on a different port, modify app.py:277:

app.py

if __name__ == "__main__":
    app.run(debug=True, port=8080)  # Changed from 5000

Or set the port via environment:

app.py

import os

if __name__ == "__main__":
    port = int(os.getenv("PORT", 5000))
    app.run(debug=True, port=port)

Then run with:

PORT=8080 python app.py

File Structure

Key application files:

.
├── app.py                  # Main Flask application (278 lines)
├── requirements.txt        # Python dependencies
├── .env.example           # Environment variable template
├── .env                   # Your configuration (create this)
├── .venv/                 # Virtual environment (created by you)
└── templates/
    └── index.html         # Web interface UI

app.py Structure

The main application file contains:

Lines	Component	Description
1-14	Imports	Flask, OpenAI, ElevenLabs, urllib
15-24	Configuration	Load env vars, set constants
27-92	Helper Functions	API clients, session management, prompt building
95-124	ElevenLabs Integration	Generic POST helper for ElevenLabs API
127-137	Text-to-Speech	Convert text to MP3 using ElevenLabs
140-162	`/tts` Endpoint	Standalone TTS endpoint
164-175	`/api/context` Endpoint	Initialize conversation session
178-223	`/api/chat` Endpoint	Main chat interface with OpenAI + ElevenLabs
226-273	`/api/call` Endpoint	Outbound phone call initiation
276-277	Server	Run Flask development server

Session Management

The app uses Flask’s encrypted session cookies to maintain conversation state: Stored in session (app.py:174-175):

business_description: Business context for the AI
scenario: Caller goal/task
messages: Conversation history (list of dicts)

Session access (app.py:53-54):

def get_session_value(key: str, default: str = ""):
    return (session.get(key) or default).strip()

Security: Sessions are encrypted using FLASK_SECRET_KEY

Sessions are stored client-side in cookies. For high-volume production use, consider Redis or database-backed sessions.

Conversation Flow Implementation

The chat endpoint maintains context using OpenAI’s message history: Initial message (app.py:193-194):

if not messages:
    messages = [{"role": "system", "content": system_prompt}]

Add user message (app.py:195):

messages.append({"role": "user", "content": user_message})

Get AI response (app.py:204-208):

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
)
agent_text = (completion.choices[0].message.content or "").strip()

Save to session (app.py:212-213):

messages.append({"role": "assistant", "content": agent_text})
session["messages"] = messages

Phone Call Implementation

Outbound calls are initiated via ElevenLabs’ Twilio integration: Payload structure (app.py:247-255):

payload = {
    "agent_id": os.getenv("ELEVENLABS_AGENT_ID"),
    "agent_phone_number_id": os.getenv("ELEVENLABS_AGENT_PHONE_NUMBER_ID"),
    "to_number": to_number,
    "conversation_initiation_client_data": {
        "conversation_config_override": {
            "agent": {
                "prompt": {"prompt": build_caller_prompt(...)},
                "first_message": build_first_message(...),
            }
        }
    },
}

Phone number validation (app.py:91-92, app.py:24):

E164_PATTERN = re.compile(r"^\+[1-9]\d{7,14}$")

def validate_phone_number(phone_number: str):
    return bool(E164_PATTERN.match((phone_number or "").strip()))

Valid formats: +15551234567, +447911123456, etc.

Troubleshooting

Import Errors

Problem: ModuleNotFoundError: No module named 'flask' Solution: Ensure your virtual environment is activated and dependencies are installed:

source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Environment Variable Issues

Problem: “ELEVENLABS_API_KEY not set in .env” Solution:

Verify .env file exists in the same directory as app.py
Check for typos in variable names

Ensure no spaces around = in .env:

ELEVENLABS_API_KEY=sk-1234  # Correct
ELEVENLABS_API_KEY = sk-1234  # Wrong

Port Already in Use

Problem: OSError: [Errno 48] Address already in use Solution: Another process is using port 5000. Either:

Kill the other process:

# Find the process
lsof -ti:5000
# Kill it
kill -9 $(lsof -ti:5000)

Change the port in app.py:277

ElevenLabs API Errors

Problem: ElevenLabs API error (401): Unauthorized Solution: Check your ELEVENLABS_API_KEY is valid and has sufficient credits. Problem: ElevenLabs API error (404) on phone calls Solution: Verify ELEVENLABS_AGENT_ID and ELEVENLABS_AGENT_PHONE_NUMBER_ID are correct.

OpenAI API Errors

Problem: Rate limit or quota exceeded Solution: The app uses gpt-4o-mini for cost efficiency (app.py:205). Check your OpenAI usage limits.

Security Best Practices

Follow these security guidelines for production deployments:

Never commit .env files - Add .env to .gitignore
Use strong secret keys - Generate with secrets.token_hex(32)
Disable debug mode - Set debug=False in production
Use HTTPS - Configure SSL/TLS on your reverse proxy
Validate inputs - The app validates phone numbers (app.py:236), but add additional input validation for your use case
Rate limiting - Implement rate limits to prevent API abuse
Environment isolation - Use separate API keys for dev/staging/production

Get Started

Testing Modes

Configuration

System Requirements

Installation Methods

Method 1: Standard Installation (Recommended)

Method 2: System-Wide Installation (Not Recommended)

Configuration

Environment Variables

Variable Reference

FLASK_SECRET_KEY (Required)

OPENAI_API_KEY (Required for chat)

ELEVENLABS_API_KEY (Required for voice)

ELEVENLABS_AGENT_ID (Required for phone calls)

ELEVENLABS_AGENT_PHONE_NUMBER_ID (Required for phone calls)

ELEVENLABS_API_BASE (Optional)

Running the Application

Development Mode

Production Mode

Custom Port

File Structure

app.py Structure

Session Management

Conversation Flow Implementation

Phone Call Implementation

Troubleshooting

Import Errors

Environment Variable Issues

Port Already in Use

ElevenLabs API Errors

OpenAI API Errors

Security Best Practices

Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

Get Started

Testing Modes

Configuration

​System Requirements

​Installation Methods

​Method 1: Standard Installation (Recommended)

​Method 2: System-Wide Installation (Not Recommended)

​Configuration

​Environment Variables

​Variable Reference

​FLASK_SECRET_KEY (Required)

​OPENAI_API_KEY (Required for chat)

​ELEVENLABS_API_KEY (Required for voice)

​ELEVENLABS_AGENT_ID (Required for phone calls)

​ELEVENLABS_AGENT_PHONE_NUMBER_ID (Required for phone calls)

​ELEVENLABS_API_BASE (Optional)

​Running the Application

​Development Mode

​Production Mode

​Custom Port

​File Structure

​app.py Structure

​Session Management

​Conversation Flow Implementation

​Phone Call Implementation

​Troubleshooting

​Import Errors

​Environment Variable Issues

​Port Already in Use

​ElevenLabs API Errors

​OpenAI API Errors

​Security Best Practices

​Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Method 1: Standard Installation (Recommended)

Method 2: System-Wide Installation (Not Recommended)

Configuration

Environment Variables

Variable Reference

FLASK_SECRET_KEY (Required)

OPENAI_API_KEY (Required for chat)

ELEVENLABS_API_KEY (Required for voice)

ELEVENLABS_AGENT_ID (Required for phone calls)

ELEVENLABS_AGENT_PHONE_NUMBER_ID (Required for phone calls)

ELEVENLABS_API_BASE (Optional)

Running the Application

Development Mode

Production Mode

Custom Port

File Structure

app.py Structure

Session Management

Conversation Flow Implementation

Phone Call Implementation

Troubleshooting

Import Errors

Environment Variable Issues

Port Already in Use

ElevenLabs API Errors

OpenAI API Errors

Security Best Practices

Next Steps