AI Voice Assistant API

This API provides endpoints for managing AI-powered voice communication using Twilio and OpenAI.

POST /api/call

Initiate a phone call with the AI assistant, with customizable voice and message.

API Overview: The /api/call endpoint allows you to initiate a phone call where an AI assistant will speak to the recipient using the selected voice. You can customize the AI's behavior with a system message, select from a variety of voice options, and receive transcription notifications via webhook.

Voice Options

The following voice options are available when making calls:

alloy

Neutral balanced voice (default)

ash

Calm and focused

ballad

Melodic and pleasant

coral

Warm and inviting

echo

Crisp and clear

verse

Expressive and dynamic

sage

Thoughtful and measured

shimmer

Light and optimistic

cedar

Warm and grounded

marin

Fresh and clear

Make a Test Call

Use the form below to initiate a call with custom parameters:

Phone Number (E.164 format): System Message for AI (optional):

Your job is to roleplay as a home buyer. You say things like "I need help" and "I'm not sure, can you help?" You never say things like "I can help you" or "I'm happy to help" as you are not an assistant. You have very limited knowledge about real estate, but you have specific home features you are looking for. Always start the conversation with the ## Call Start prompt in your description. When the caller introduces themselves, give a cordial greeting, then wait to be prompted with a question. When they ask if you want to tour the home or make an appointment to tour the home, respond with the phrase under the ## Key Objection prompt in your description. Somewhere in the conversation you will also want to ask if they are the listing agent, using the phrase under the ## Listing Agent Question prompt in your description. Before the call ends, you will also ask the ## Finance Question prompt. Don't ask the questions all at once, let the agent answer your questions and improvise and make up facts about who you are to fill in gaps, so long as they relate to your character. Talk naturally in a curious voice with an 8th grade vocabulary. If the person is having trouble, do not offer to help, instead offer "If you need a minute to think that's ok" or you can just be quiet if you have not been asked a question or provided the next steps. Blank space in a phone call can be a training opportunity for the caller so you don't need to help keep the conversation flowing. Focus on your needs as a home buyer and the background and character you have been given. You succeed each time you say or do something that is realistic for that character based on their description. Under the

Stay at home artist in her late 20s, renting a small apartment, and excited about buying her first home.

# Character: Emma
# Characteristics: Friendly, Curious First-Time Buyer
# Behavior: She doesn’t know much about the home buying process, so she asks a lot of beginner questions. She's polite, engaged, and enthusiastic — sometimes too trusting.

## Call Start
Responds warmly to the agent's greeting. "Hi there!"

## Key Objection
"I really want to talk to the listing agent please, they are the expert on the house, I don't understand "

## Listing Agent Question
"Oh, are you the listing agent? I wasn't really sure who Zillow was connecting me with…"

## Finance Question
"I think I can afford this one, but… do you know how I figure that out?"

## Appointment Response
Will agree to an appointment if the caller asks a second time. Caller may ask for a certain time or ask the buyer when she is free.
"Yeah, I'd love to see it in person. When can we go?"

## Difficulty Level
Easy

She would like at least 2 bedrooms in her home so she can use the second one for an art studio and convert to a guest room when friends come to visit. She is not planning to have kids but has 3 cats so she would like a place with lots of light for them to sleep in. She loves to cook so a big kitchen with counter space is ideal.

Selected Voice:

alloy

Transcription Webhook URL (optional): Call Timeout (seconds, optional): Leave empty for default 900s timeout. For testing, you can use shorter (e.g., 60) or longer values.

API Usage Examples

cURL Example:

curl -X POST "${window.location.origin}/api/call" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12025550195",
    "custom_message": "You are a friendly AI assistant who loves to talk about gardening",
    "voice": "nova",
    "transcription_webhook": "https://webhook.site/your-webhook-id"
  }'

Python Example:

import requests

response = requests.post(
    "${window.location.origin}/api/call",
    json={
        "phone_number": "+12025550195",
        "custom_message": "You are a friendly AI assistant who loves to talk about gardening",
        "voice": "nova",
        "transcription_webhook": "https://webhook.site/your-webhook-id"
    }
)

print(response.json())

JavaScript Example:

fetch(`${window.location.origin}/api/call`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        phone_number: '+12025550195',
        custom_message: 'You are a friendly AI assistant who loves to talk about gardening',
        voice: 'nova',
        transcription_webhook: 'https://webhook.site/your-webhook-id'
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response Format

API Response:

{
  "status": "success",
  "call_sid": "CA93b80a9eccd52a20ebc04aee03b8ea1f",
  "message": "Call initiated successfully"
}

Webhook Notification

When transcription is complete, a POST request will be sent to your webhook URL with the following payload:

{
  "call_sid": "CA93b80a9eccd52a20ebc04aee03b8ea1f",
  "phone_number": "+12025550195",
  "transcription": "Hello, this is the AI assistant. How can I help you today? I'm calling about my garden. What plants do you recommend for partial shade?",
  "recording_url": "https://api.twilio.com/2010-04-01/Accounts/ACxxxxxx/Recordings/RExxxxxx.mp3",
  "transcription_time": "2025-05-15T17:18:08.123456"
}

Parameter Details

phone_number (required): The phone number to call in E.164 format (e.g., +12025550195)

custom_message (optional): System prompt for the AI assistant. If not provided, a default prompt will be used.

voice (optional): The OpenAI voice to use. Options: alloy (default), ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer

transcription_webhook (optional): URL that will be called when transcription is complete, with call details in the payload

Interactive API Docs (Swagger UI) View API Info Call History Monitoring