PraisonAI Call

Guide to PraisonAI’s voice-based interaction feature enabling AI customer service through phone calls, including setup and tool integration

Turn an Agent into a phone assistant — start the call server and connect a phone number to talk to it over the line.

export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
export NGROK_AUTH_TOKEN="${NGROK_AUTH_TOKEN:?Set NGROK_AUTH_TOKEN in your shell}"
praisonai call --public

AI Customer Service

PraisonAI Call is a feature that enables voice-based interaction with AI models through phone calls. This functionality allows users to have natural conversations with AI agents over traditional phone lines.

Installation

Step 1

pip install "praisonai[call]"
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
export NGROK_AUTH_TOKEN="${NGROK_AUTH_TOKEN:?Set NGROK_AUTH_TOKEN in your shell}"
praisonai call --public

Step 2

Buy a number at PraisonAI Dashboard

Step 3

Enter the Public URL in the PraisonAI Dashboard phone number field

Authentication

Breaking Change: When upgrading from earlier versions, the call server requires authentication configuration or it will fail with a 503 error.

The PraisonAI Call server now requires authentication configuration for security. You have two options:

Option 1: Token Authentication (Recommended)

Set a secure token for API authentication:

export CALL_SERVER_TOKEN="${CALL_SERVER_TOKEN:?Set CALL_SERVER_TOKEN in your shell}"
praisonai call --public

API requests must include the token in the Authorization header:

curl -H "Authorization: Bearer ${CALL_SERVER_TOKEN:?Set CALL_SERVER_TOKEN in your shell}" \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello"}' \
     http://localhost:8090/api/v1/agents/assistant/invoke

Option 2: Disable Authentication (Local Development Only)

For local development on your own machine, you can disable authentication. The CLI sets the bind-host env var for you, so this is enough when launching via praisonai call:

export PRAISONAI_CALL_AUTH=disabled
praisonai call

If you launch the server programmatically (custom uvicorn, embedding praisonai.api.agent_invoke in another app, or any path that does NOT go through praisonai call / praisonai serve), you must also pin the bind host:

export PRAISONAI_CALL_AUTH=disabled
export PRAISONAI_CALL_BIND_HOST=127.0.0.1

Without PRAISONAI_CALL_BIND_HOST set to a localhost value, every request is rejected with:

503 Service Unavailable
PRAISONAI_CALL_AUTH=disabled is only permitted for localhost binding;
set PRAISONAI_CALL_BIND_HOST to 127.0.0.1 when binding locally

Never use PRAISONAI_CALL_AUTH=disabled in production. It is rejected outright unless the server is bound to localhost, and even then it bypasses all caller verification.

Authentication Flow

When CALL_SERVER_TOKEN is not configured and the environment is not development, the server returns:

503 Service Unavailable
CALL_SERVER_TOKEN is not configured. Set CALL_SERVER_TOKEN or PRAISONAI_CALL_AUTH=disabled to run without authentication.

When PRAISONAI_CALL_AUTH=disabled is set but the bind host is not localhost:

503 Service Unavailable
PRAISONAI_CALL_AUTH=disabled is only permitted for localhost binding;
set PRAISONAI_CALL_BIND_HOST to 127.0.0.1 when binding locally

Environment Variables

Env var	Required when	Effect
CALL_SERVER_TOKEN	Production / any non-local exposure	Server requires Authorization: Bearer <token>
PRAISONAI_CALL_AUTH=disabled	Local development only	Bypasses auth — only honored if PRAISONAI_CALL_BIND_HOST is localhost
PRAISONAI_CALL_BIND_HOST	Whenever you launch without the praisonai call/praisonai serve CLI	Declares the real bind host so the auth-disabled guard can verify it

Binding & Network Access

The call server binds to 127.0.0.1 by default, so it is only reachable from the same machine.

# Local development (default — same machine only)
praisonai call

# Specific port, still localhost-only
praisonai call --port 8090

# Expose on LAN (warning will be printed)
praisonai call --host 0.0.0.0 --port 8090

# Expose publicly via ngrok
export NGROK_AUTH_TOKEN="${NGROK_AUTH_TOKEN:?Set NGROK_AUTH_TOKEN in your shell}"
praisonai call --public

Breaking change (earlier versions → this release): Earlier versions of praisonai call bound to 0.0.0.0 unconditionally, exposing the server to your entire LAN. Starting in this release, the default is 127.0.0.1. Production deployments that previously relied on the LAN-exposed default must add --host 0.0.0.0 (or a specific NIC) and ensure CALL_SERVER_TOKEN is set.

Features

• Make and receive phone calls with AI agents
• Natural language processing for voice interactions
• Support for multiple phone carriers and providers
• Call recording and transcription capabilities
• Integration with other PraisonAI features

Adding Tools

1. Create a file called tools.py
2. Add the following code:

import yfinance as yf

# Get Stock Price definition
get_stock_price_def = {
    "name": "get_stock_price",
    "description": "Get the current stock price for a given ticker symbol",
    "parameters": {
        "type": "object", 
        "properties": {
            "ticker_symbol": {
                "type": "string", 
                "description": "The ticker symbol of the stock (e.g., AAPL, GOOGL)"
            }
        }, 
        "required": ["ticker_symbol"]
    }
}

# Get Stock Price function / Tool
async def get_stock_price_handler(ticker_symbol):
    try:
        stock = yf.Ticker(ticker_symbol)
        hist = stock.history(period="1d")
        if hist.empty:
            return {"error": f"No data found for ticker {ticker_symbol}"}
        current_price = hist['Close'].iloc[-1]  # Using -1 is safer than 0
        return {"price": str(current_price)}
    except Exception as e:
        return {"error": str(e)}



get_stock_price = (get_stock_price_def, get_stock_price_handler)
tools = [
    get_stock_price
]

pip install yfinance

4. ```bash
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
export NGROK_AUTH_TOKEN="${NGROK_AUTH_TOKEN:?Set NGROK_AUTH_TOKEN in your shell}"
praisonai call --public

Manage Google Calendar Events

See Google Calendar Tools

Deploy

Docker Deployment

# Use an official Python runtime as a parent image
FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONUNBUFFERED 1

# Set work directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install PraisonAI with the 'call' extra and ensure it's the latest version
RUN pip install --no-cache-dir --upgrade "praisonai[call]"

# Expose the port the app runs on
EXPOSE 8090

# Bind to all container interfaces — the container boundary is the security boundary.
# Pair with CALL_SERVER_TOKEN for any externally-published port.
CMD ["praisonai", "call", "--host", "0.0.0.0"]

How It Works

A caller dials your number, the provider forwards audio to the call server, and the Agent responds with synthesized speech.

Best Practices

Always set CALL_SERVER_TOKEN in production

The server fails with 503 unless a token is set or auth is explicitly disabled for localhost. Never disable auth on a public bind.

Keep the default localhost bind

praisonai call binds to 127.0.0.1 by default. Add --host 0.0.0.0 only inside a container or when you deliberately expose the LAN.

Set secrets via environment variables

Export OPENAI_API_KEY, NGROK_AUTH_TOKEN, and CALL_SERVER_TOKEN in your shell — never inline the raw values.

Add tools for real actions

Register async tool handlers (like a stock-price lookup) so the phone agent can fetch live data during a call.

Related

Tools

Give your call agent live data and actions.

Security

Harden the call server before exposing it.