Skip to main content

​
Overview

This quickstart guide will walk you through setting up the AI Voice Testing Platform and running your first test conversation. You’ll be up and running in just a few minutes.
For web chat testing, you only need OpenAI and ElevenLabs API keys. Phone calling requires additional ElevenLabs Conversational AI setup.

​
Prerequisites

Before you begin, ensure you have:

​
Step 1: Install Dependencies

1

Create a virtual environment

Navigate to your project directory and create a Python virtual environment:
python -m venv .venv
This isolates your project dependencies from your system Python installation.
2

Activate the virtual environment

source .venv/bin/activate
You should see (.venv) appear in your terminal prompt.
3

Install required packages

Install all dependencies from requirements.txt:
pip install -r requirements.txt
This installs:
  • flask==3.0.0 - Web framework
  • elevenlabs==1.14.0 - Voice synthesis SDK
  • python-dotenv==1.0.0 - Environment variable management
  • openai==1.55.0 - OpenAI SDK for chat

​
Step 2: Configure Environment Variables

1

Copy the example environment file

Create your .env file from the template:
cp .env.example .env
2

Add your API keys

Open .env in your text editor and replace the placeholder values:
.env
FLASK_SECRET_KEY=your-random-secret-key-here
ELEVENLABS_API_KEY=your-elevenlabs-api-key
OPENAI_API_KEY=your-openai-api-key
ELEVENLABS_AGENT_ID=replace-me
ELEVENLABS_AGENT_PHONE_NUMBER_ID=replace-me
Generate a strong random value for FLASK_SECRET_KEY in production. You can use:
python -c "import secrets; print(secrets.token_hex(32))"
3

Verify your configuration

For web chat testing, you need at minimum:
  • FLASK_SECRET_KEY
  • OPENAI_API_KEY
  • ELEVENLABS_API_KEY
The agent and phone number IDs are only required for outbound phone calls.

​
Step 3: Run the Application

Start the Flask development server: 
python app.py
You should see output like: 
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000
The app runs on port 5000 by default. If this port is in use, you can change it in app.py:277.

​
Step 4: Start Your First Conversation

1

Open the web interface

Navigate to http://localhost:5000 in your browser.
2

Enter business context

In the business description field, describe your phone system:Example:
A dental office with automated scheduling. We handle appointment bookings,
cancellations, and insurance verification. Office hours are 9am-5pm Mon-Fri.
3

Define a caller scenario

Specify what the AI caller should try to accomplish:Example:
check appointment availability for a teeth cleaning next week
If you leave this blank, the default scenario is: “check availability, complete a typical customer task, and avoid speaking to a human if possible”
4

Start the conversation

Click Start conversation. The AI will initiate the chat with a greeting based on your scenario.The AI caller will say something like:
Hi, I'm calling because I'd like to check appointment availability for a teeth cleaning next week.
5

Respond as your business

Type your response as if you’re the business’s phone system or operator:Example:
Thank you for calling. I can help you with that. What day works best for you?
The AI will:
  • Generate a conversational response using OpenAI GPT-4o-mini
  • Synthesize speech using ElevenLabs TTS
  • Return both text and audio to your browser
6

Continue the conversation

Keep responding to test your entire phone flow. The AI maintains context across the conversation and attempts to complete the task naturally.

​
Understanding the Chat Flow

Here’s what happens behind the scenes when you send a message:
  1. Context Building - Your message is added to the conversation history maintained in Flask session (app.py:191-195)
  2. Prompt Construction - The system builds a caller prompt using build_caller_prompt() that includes your business description and scenario (app.py:57-66)
  3. AI Response - OpenAI’s gpt-4o-mini model generates a response (app.py:204-208)
  4. Voice Synthesis - ElevenLabs converts the text to speech using the eleven_turbo_v2_5 model with voice ID JBFqnCBsd6RMkjVDRZzb (app.py:132-136)
  5. Response Delivery - Both text and base64-encoded audio are returned to the browser (app.py:223)

​
Testing Outbound Phone Calls (Optional)

To test real phone calls, you need to configure ElevenLabs Conversational AI:
1

Create an ElevenLabs Conversational AI agent

  1. Log into your ElevenLabs dashboard
  2. Navigate to Conversational AI
  3. Create a new agent or select an existing one
  4. Enable prompt overrides - This allows the app to inject your business description at call time
  5. Copy the Agent ID
2

Connect a Twilio phone number

  1. In ElevenLabs, import or connect a Twilio-backed phone number
  2. Copy the Phone Number ID
  3. This number will be used as the caller ID for outbound calls
3

Update your .env file

Add the IDs to your .env:
ELEVENLABS_AGENT_ID=your-agent-id-here
ELEVENLABS_AGENT_PHONE_NUMBER_ID=your-phone-number-id-here
4

Make a test call

Back in the web interface:
  1. Enter your business description and scenario
  2. Enter a destination phone number in E.164 format (e.g., +15551234567)
  3. Click Start call
The backend calls ElevenLabs’ /v1/convai/twilio/outbound-call endpoint (app.py:258), which initiates a real phone call using the same caller context as web chat.
Outbound calls consume ElevenLabs and Twilio credits. Always test your scenarios in web chat mode first before making real phone calls.

​
API Endpoints Reference

The platform exposes these endpoints:
EndpointMethodPurpose
/GETServes the main web interface (app.py:141)
/api/contextPOSTSets business description and initializes session (app.py:164)
/api/chatPOSTSends a message and receives AI response with audio (app.py:178)
/api/callPOSTInitiates an outbound phone call (app.py:226)
/ttsPOSTStandalone text-to-speech conversion (app.py:145)

​
Next Steps

Installation Guide

Learn about production deployment and advanced configuration

API Reference

Explore detailed API documentation and integration options

​
Troubleshooting

​
”ELEVENLABS_API_KEY not set in .env”

Make sure your .env file is in the same directory as app.py and contains valid API keys.

​
”Missing required environment variables”

For phone calls, you must set ELEVENLABS_AGENT_ID and ELEVENLABS_AGENT_PHONE_NUMBER_ID in addition to the API keys.

​
”Phone number must be in E.164 format”

Phone numbers must start with + followed by country code and number. For example:
  • US: +15551234567
  • UK: +447911123456
The validation regex is defined in app.py:24.

​
No audio in web chat

If you receive text responses but no audio, check:
  1. Your ELEVENLABS_API_KEY is valid
  2. Your ElevenLabs account has sufficient credits
  3. Browser console for any audio playback errors

Build docs developers (and LLMs) love

Get started for freeTalk to us