Voice Call API

curl --request GET \
  --url http://127.0.0.1:8765/status \
  --header 'X-API-Key: <api-key>'

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))

}

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

GET

status

Voice Call API

curl --request GET \
  --url http://127.0.0.1:8765/status \
  --header 'X-API-Key: <api-key>'

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))

}

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.

/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.

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.

/media-stream

WebSocket for audio streaming

Connection Flow

Twilio connects to WebSocket
Server connects to OpenAI Realtime API
Audio streams bidirectionally:
- Twilio → Server → OpenAI (user speech)
- OpenAI → Server → Twilio (AI response)

Twilio Events

Event	Description
`start`	Stream started
`media`	Audio data chunk
`stop`	Stream ended

OpenAI Events

Event	Description
`session.created`	Session initialized
`session.updated`	Session config updated
`input_audio_buffer.speech_started`	User started speaking
`input_audio_buffer.speech_stopped`	User stopped speaking
`response.audio.delta`	AI audio response chunk
`response.done`	AI response complete

Configuration

Environment Variables

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes*	-	OpenAI API key with Realtime access (*required unless `PRAISONAI_REALTIME_API_KEY` is set)
`PORT`	No	`8090`	Server port
`NGROK_AUTH_TOKEN`	No	-	ngrok token for public URL
`PUBLIC`	No	`false`	Enable public URL via ngrok
`PRAISONAI_REALTIME_URL`	No	(OpenAI)	Full `wss://…` URL — takes precedence over the OpenAI default
`PRAISONAI_REALTIME_MODEL`	No	`gpt-4o-realtime-preview-2024-10-01`	Model for the default OpenAI URL
`PRAISONAI_REALTIME_API_KEY`	No	falls back to `OPENAI_API_KEY`	Bearer key for the realtime connection

Realtime Timeouts

The realtime WebSocket runs with bounded connect / heartbeat / close so a dead upstream cannot hold a Twilio media leg indefinitely: open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=5, max_size=1 MiB. These are hardcoded, not env-tunable. See Point the realtime endpoint elsewhere for the override flow.

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

Get your public URL (ngrok or deployed)
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
  }
}

Point the realtime endpoint elsewhere - Azure / self-hosted realtime overrides
CLI - Command-line interface
Agent - Agent configuration

​Voice Call API

​Binding

​Base URL

​Endpoints

​Status Page

​Incoming Call Handler

​Media Stream WebSocket

​Configuration

​Environment Variables

​Realtime Timeouts

​Custom Tools

​Usage Example

​Start Server

​Twilio Configuration

​Python Usage

​Session Configuration

​Related

Voice Call API

Binding

Base URL

Endpoints

Status Page

Incoming Call Handler

Media Stream WebSocket

Configuration

Environment Variables

Realtime Timeouts

Custom Tools

Usage Example

Start Server

Twilio Configuration

Python Usage

Session Configuration

Related