Environment Variables

The AI Voice Testing Platform uses environment variables to configure API keys, service credentials, and application settings. All variables should be defined in a .env file in the root directory.

Setup

Copy the .env.example file to create your .env file:

cp .env.example .env

Then fill in the required values as described below.

Environment Variables Reference

FLASK_SECRET_KEY

string

required

Secret key used by Flask to sign session cookies and protect against CSRF attacks.

Default Value: dev-secret-change-in-production Usage in Code:

app.py:18

app.secret_key = os.getenv("FLASK_SECRET_KEY", "dev-secret-change-in-production")

The default value is only for development. You must set a secure, random value in production to protect user sessions.

How to Generate:

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

Example:

FLASK_SECRET_KEY=a1b2c3d4e5f6789012345abcdef67890abcdef1234567890abcdef123456789

ELEVENLABS_API_KEY

string

required

ElevenLabs API key for text-to-speech and conversational AI phone calls.

Required For:

Text-to-speech audio generation in web chat (/tts endpoint)
Outbound phone calls through ElevenLabs + Twilio integration (/api/call endpoint)

Usage in Code:

app.py:28

api_key = os.getenv("ELEVENLABS_API_KEY")
if not api_key:
    return None

Where to Get:

Sign up at elevenlabs.io
Navigate to your profile settings
Generate an API key from the API section

Example:

ELEVENLABS_API_KEY=sk_1234567890abcdef1234567890abcdef

The application will function without this key, but TTS features will be disabled and the /api/call endpoint will return an error.

OPENAI_API_KEY

string

required

OpenAI API key used to power the conversational AI agent in web chat mode.

Required For:

Web chat agent responses (/api/chat endpoint)
Generating contextual customer/caller dialogue based on business descriptions

Usage in Code:

app.py:197-209

openai_key = os.getenv("OPENAI_API_KEY")
if not openai_key:
    agent_text = "I'd like to know more about your business. (Set OPENAI_API_KEY in .env for full conversation.)"
else:
    from openai import OpenAI
    client = OpenAI(api_key=openai_key)
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,
    )

Model Used: gpt-4o-mini Where to Get:

Sign up at platform.openai.com
Navigate to API keys section
Create a new API key

Example:

OPENAI_API_KEY=sk-proj-abcdef123456789012345678901234567890abcdef1234567890

Without this key, the web chat will return a fallback message instead of generating intelligent responses.

ELEVENLABS_AGENT_ID

string

required

ElevenLabs Conversational AI agent ID used for outbound phone calls.

Required For:

Outbound phone calls (/api/call endpoint)

Usage in Code:

app.py:239-245

missing_env = [
    name
    for name in ("ELEVENLABS_API_KEY", "ELEVENLABS_AGENT_ID", "ELEVENLABS_AGENT_PHONE_NUMBER_ID")
    if not os.getenv(name)
]
if missing_env:
    return jsonify({"error": f"Missing required environment variables: {', '.join(missing_env)}"}), 500

Where to Get:

Log into your ElevenLabs account
Navigate to Conversational AI section
Create or select an existing agent
Copy the agent ID from the agent settings

The agent should have prompt overrides enabled to allow the application to inject custom business descriptions and scenarios at call time.

Example:

ELEVENLABS_AGENT_ID=agent_abc123def456

See ElevenLabs Setup for detailed instructions.

ELEVENLABS_AGENT_PHONE_NUMBER_ID

string

required

ElevenLabs phone number ID connected to Twilio for outbound calling.

Required For:

Outbound phone calls (/api/call endpoint)

Usage in Code:

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": build_conversation_initiation_data(
        business_description,
        scenario,
    ),
}

Where to Get:

In ElevenLabs, navigate to Phone Numbers section
Import or connect a Twilio-backed phone number
Copy the phone number ID from the phone number settings

Example:

ELEVENLABS_AGENT_PHONE_NUMBER_ID=phone_xyz789abc123

This phone number must be properly connected to your Twilio account through ElevenLabs. Without proper configuration, outbound calls will fail.

See ElevenLabs Setup for step-by-step phone number configuration.

Optional Environment Variables

ELEVENLABS_API_BASE

string

default:"https://api.elevenlabs.io"

Base URL for ElevenLabs API. Override this if using a custom endpoint or proxy.

Usage in Code:

app.py:20

ELEVENLABS_API_BASE = os.getenv("ELEVENLABS_API_BASE", "https://api.elevenlabs.io").rstrip("/")

Example:

ELEVENLABS_API_BASE=https://api.elevenlabs.io

Most users do not need to set this variable. The default value works for standard ElevenLabs accounts.

Validation Logic

Phone Number Format

When making outbound calls, phone numbers must be in E.164 format:

app.py:24,91-92

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 Examples:

+15551234567 (US)
+442071234567 (UK)
+81312345678 (Japan)

Invalid Examples:

5551234567 (missing + and country code)
+1 555 123 4567 (contains spaces)
(555) 123-4567 (formatting characters)

Missing Variable Handling

Web Chat - Missing OPENAI_API_KEY

The application will return a fallback message:

app.py:199

agent_text = "I'd like to know more about your business. (Set OPENAI_API_KEY in .env for full conversation.)"

Chat functionality works but responses are not intelligent.

Text-to-Speech - Missing ELEVENLABS_API_KEY

TTS endpoint returns an error:

app.py:154

return jsonify({"error": "ELEVENLABS_API_KEY not set in .env"}), 500

Web chat will still return text responses but without audio.

Outbound Calls - Missing Required Variables

The /api/call endpoint validates all three ElevenLabs variables:

app.py:239-245

missing_env = [
    name
    for name in ("ELEVENLABS_API_KEY", "ELEVENLABS_AGENT_ID", "ELEVENLABS_AGENT_PHONE_NUMBER_ID")
    if not os.getenv(name)
]
if missing_env:
    return jsonify({"error": f"Missing required environment variables: {', '.join(missing_env)}"}), 500

All three must be set for phone calls to work.

Complete Example .env File

# Flask Configuration
FLASK_SECRET_KEY=a1b2c3d4e5f6789012345abcdef67890abcdef1234567890abcdef123456789

# ElevenLabs Configuration
ELEVENLABS_API_KEY=sk_1234567890abcdef1234567890abcdef
ELEVENLABS_AGENT_ID=agent_abc123def456
ELEVENLABS_AGENT_PHONE_NUMBER_ID=phone_xyz789abc123

# OpenAI Configuration
OPENAI_API_KEY=sk-proj-abcdef123456789012345678901234567890abcdef1234567890

# Optional: Custom ElevenLabs API Base (uncomment if needed)
# ELEVENLABS_API_BASE=https://api.elevenlabs.io

Quick Reference Table

Variable	Required	Used For	Default
`FLASK_SECRET_KEY`	Yes	Session security	`dev-secret-change-in-production`
`ELEVENLABS_API_KEY`	Yes	TTS & phone calls	None
`OPENAI_API_KEY`	Yes	Web chat AI	None
`ELEVENLABS_AGENT_ID`	For calls	Outbound calling	None
`ELEVENLABS_AGENT_PHONE_NUMBER_ID`	For calls	Outbound calling	None
`ELEVENLABS_API_BASE`	No	Custom endpoint	`https://api.elevenlabs.io`

Get Started

Testing Modes

Configuration

Setup

Environment Variables Reference

FLASK_SECRET_KEY

ELEVENLABS_API_KEY

OPENAI_API_KEY

ELEVENLABS_AGENT_ID

ELEVENLABS_AGENT_PHONE_NUMBER_ID

Optional Environment Variables

ELEVENLABS_API_BASE

Validation Logic

Phone Number Format

Missing Variable Handling

Complete Example .env File

Quick Reference Table

Next Steps

ElevenLabs Setup

Quick Start

Build docs developers (and LLMs) love

Get Started

Testing Modes

Configuration

​Setup

​Environment Variables Reference

​FLASK_SECRET_KEY

​ELEVENLABS_API_KEY

​OPENAI_API_KEY

​ELEVENLABS_AGENT_ID

​ELEVENLABS_AGENT_PHONE_NUMBER_ID

​Optional Environment Variables

​ELEVENLABS_API_BASE

​Validation Logic

​Phone Number Format

​Missing Variable Handling

​Complete Example .env File

​Quick Reference Table

​Next Steps

ElevenLabs Setup

Quick Start

Build docs developers (and LLMs) love

Setup

Environment Variables Reference

FLASK_SECRET_KEY

ELEVENLABS_API_KEY

OPENAI_API_KEY

ELEVENLABS_AGENT_ID

ELEVENLABS_AGENT_PHONE_NUMBER_ID

Optional Environment Variables

ELEVENLABS_API_BASE

Validation Logic

Phone Number Format

Missing Variable Handling

Complete Example .env File

Quick Reference Table

Next Steps