Skip to main content
GET
/
status
Voice Call API
curl --request GET \
  --url http://127.0.0.1:8765/status \
  --header 'X-API-Key: <api-key>'
import requests

url = "http://127.0.0.1:8765/status"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('http://127.0.0.1:8765/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("http://127.0.0.1:8765/status")
  .header("X-API-Key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/status")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

​
Voice Call API

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

​
Binding

praisonai call binds to 127.0.0.1:8090 by default. Inside a container or VM, use --host 0.0.0.0 so the server is reachable from outside the container boundary — see Binding & Network Access for details. Always pair an exposed port with CALL_SERVER_TOKEN. 
# Inside a container / pod (the container IS the isolation boundary)
praisonai call --host 0.0.0.0 --port 8090

​
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 (local only, default)
run_server(port=8090)

# Start with public ngrok tunnel
run_server(port=8090, use_public=True)

# Start bound to all interfaces (e.g. inside a container)
run_server(port=8090, host="0.0.0.0")

​
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