Skip to main content

​
What is Sonore Phone Agent?

Sonore Phone Agent is a production-ready, AI-powered phone system that handles business calls using OpenAI’s Realtime API. Built on FastAPI and Python 3.12+, it provides a complete solution for managing voice interactions with real-time AI capabilities, multi-tenant support, and enterprise-grade reliability. The system processes incoming phone calls, engages callers with natural conversations, executes custom tools (like call transfers), and provides detailed transcripts and analytics for every interaction.

Quick Start

Get your first phone agent running in under 5 minutes

Architecture

Understand the system design and data flow

Call Lifecycle

Learn how calls are processed from webhook to completion

Multi-Tenancy

Configure isolated environments for different clients

​
Key Features

Sonore Phone Agent delivers enterprise-grade voice AI capabilities:
Native integration with OpenAI’s Realtime API for low-latency voice interactions. Supports WebSocket-based bidirectional audio streaming with automatic speech recognition and text-to-speech synthesis.
Complete isolation between tenants with dedicated configurations, prompts, and tools. Each tenant gets their own phone number routing, capacity limits, and customization options.
# Example: Tenant resolution from dialed number
tenant_resolver = TenantResolver()
tenant_id = await tenant_resolver.resolve_tenant(dialed_number)
Intelligent call routing with configurable limits at both global and per-tenant levels. The system automatically rejects calls when capacity is reached and tracks pending vs. active sessions.
# From src/apps/calls/app/call_manager.py:32
max_concurrent: int = settings.max_concurrent_calls
Extensible framework for executing actions during calls. Built-in support for call transfers with a pluggable architecture for adding custom tools.
# From src/apps/calls/app/call_session.py:524
async def handle_tool_execution(
    self, invocation: ToolInvocation
) -> ToolResult:
    result = await self.tool_executor.execute(invocation)
    return result
WebSocket-based call sessions with comprehensive state tracking. Each session manages its own lifecycle, tool invocations, and transcript collection.
# From src/apps/calls/app/call_session.py:29
class CallSessionStatus(str, Enum):
    NEW = "new"
    RUNNING = "running"
    STOPPING = "stopping"
    FINISHED = "finished"
    FAILED = "failed"
    CANCELLED = "cancelled"
Automatic transcript generation and post-call webhook processing. Every completed call triggers a processing pipeline for summarization and analytics.
# From src/apps/calls/app/call_session.py:616
async def post_process(self) -> None:
    url = f"{settings.post_call_uri}/api/v1/process"
    payload = {"call_id": self.call_id, "tenant_id": self.tenant_id}
    # Retry logic with exponential backoff
Scalable storage for call registries, transcripts, tenant configurations, and system prompts. Uses async MongoDB client for non-blocking database operations.
# From src/apps/calls/main.py:43
mongo_client = AsyncMongoClient(settings.mongodb_uri.get_secret_value())
Secure webhook verification with built-in deduplication and capacity gating. Handles OpenAI SIP call events including incoming calls, hangups, and call completion.
# From src/apps/calls/api/v1/endpoints/openai_webhook.py:74
event = client.webhooks.unwrap(
    raw_body,
    headers=headers,
    secret=settings.openai_webhook_secret.get_secret_value(),
)

​
Use Cases

Sonore Phone Agent is designed for businesses that need intelligent phone automation:
  • Customer Support: Handle common inquiries with natural conversations
  • Appointment Scheduling: Book meetings and send confirmations
  • Lead Qualification: Screen and route high-value prospects
  • Call Routing: Transfer calls to appropriate departments or specialists
  • After-Hours Service: Provide 24/7 availability for customer needs
  • Survey Collection: Gather feedback with conversational interviews

​
Technology Stack

FastAPI

High-performance async web framework

OpenAI Realtime API

Real-time voice AI capabilities

MongoDB

Scalable document database

Python 3.12+

Modern Python with async/await

WebSockets

Bidirectional streaming connections

Pydantic

Data validation and settings

​
Getting Started

1

Install Dependencies

Set up your Python environment and install required packages
uv venv
source .venv/bin/activate
uv pip install -e .
2

Configure Environment

Create your .env file with required credentials
OPENAI_API_KEY=sk-...
OPENAI_WEBHOOK_SECRET=whsec_...
MONGODB_URI=mongodb://localhost:27017
3

Run the Services

Start the call handler and post-call processor
uvicorn src.apps.calls.main:app --reload
uvicorn src.apps.post_call.main:app --port 8001 --reload
4

Test Your Setup

Verify the system is ready to receive calls
curl http://localhost:8000/health
Ready to dive deeper? Continue to the Quickstart Guide for a complete walkthrough, or explore the Architecture to understand how everything works together.

​
Support and Resources

Configuration Guide

Set up environment variables and system settings

API Reference

Explore webhook endpoints and admin APIs

Deployment Guide

Deploy with Docker and production best practices

Troubleshooting

Common issues and how to resolve them

Build docs developers (and LLMs) love

Get started for freeTalk to us