Skip to main content
GET
/
status
Voice Call API
curl --request GET \
  --url https://api.example.com/status \
  --header 'Authorization: Bearer <token>'

​
Voice Call API

The Voice Call API provides Twilio voice integration with OpenAI’s Realtime API for voice-based AI interactions.

​
Base URL

http://localhost:8090

​
Endpoints

​
Status Page

Check if the server is running.
​
GET
/status
Returns HTML status page
Response 
<html>
  <head><title>Praison AI Call Server</title></head>
  <body>
    <h1>Praison AI Call Server is running!</h1>
  </body>
</html>

​
Incoming Call Handler

Handle incoming Twilio calls and return TwiML response.
​
GET/POST
/
Twilio webhook for incoming calls
Response (TwiML) 
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say></Say>
  <Pause length="1"/>
  <Connect>
    <Stream url="wss://your-host/media-stream"/>
  </Connect>
</Response>

​
Media Stream WebSocket

WebSocket endpoint for real-time audio streaming between Twilio and OpenAI.
​
WebSocket
/media-stream
WebSocket for audio streaming
Connection Flow
  1. Twilio connects to WebSocket
  2. Server connects to OpenAI Realtime API
  3. Audio streams bidirectionally:
    • Twilio → Server → OpenAI (user speech)
    • OpenAI → Server → Twilio (AI response)
Twilio Events
EventDescription
startStream started
mediaAudio data chunk
stopStream ended
OpenAI Events
EventDescription
session.createdSession initialized
session.updatedSession config updated
input_audio_buffer.speech_startedUser started speaking
input_audio_buffer.speech_stoppedUser stopped speaking
response.audio.deltaAI audio response chunk
response.doneAI response complete

​
Configuration

​
Environment Variables

VariableRequiredDefaultDescription
OPENAI_API_KEYYes-OpenAI API key with Realtime access
PORTNo8090Server port
NGROK_AUTH_TOKENNo-ngrok token for public URL
PUBLICNofalseEnable public URL via ngrok

​
Custom Tools

Create a tools.py file in the working directory: 
# tools.py
async def get_weather(location: str) -> dict:
    """Get weather for a location."""
    return {"location": location, "temp": "72°F", "condition": "sunny"}

get_weather.definition = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
    }
}

tools = [(get_weather.definition, get_weather)]

​
Usage Example

​
Start Server

# Basic start
python -m praisonai.api.call

# With public URL
python -m praisonai.api.call --public

# Custom port
python -m praisonai.api.call --port 9000

​
Twilio Configuration

  1. Get your public URL (ngrok or deployed)
  2. In Twilio Console:
    • Go to Phone Numbers → Your Number
    • Set Voice webhook to: https://your-url.ngrok.io/
    • Method: POST

​
Python Usage

from praisonai.api.call import run_server

# Start the server
run_server(port=8090, use_public=True)

​
Session Configuration

The server sends this session configuration to OpenAI: 
{
  "type": "session.update",
  "session": {
    "turn_detection": {
      "type": "server_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 200
    },
    "input_audio_format": "g711_ulaw",
    "output_audio_format": "g711_ulaw",
    "voice": "alloy",
    "tools": [],
    "tool_choice": "auto",
    "modalities": ["text", "audio"],
    "temperature": 0.8
  }
}
  • CLI - Command-line interface
  • Agent - Agent configuration