Skip to main content
The Sonore Phone Agent uses environment variables for configuration. All settings are defined in src/core/settings.py and loaded from a .env file.

​
Configuration Loading

The application uses Pydantic settings with the following behavior:
  • Reads from .env file in the project root
  • Environment variables override .env file values
  • Case-insensitive variable names
  • Extra unknown variables are ignored

​
General Settings

​
APP_NAME
string
default:"sonore-phone-agent"
Application name identifier
​
DEBUG
boolean
default:"false"
Enable debug mode for verbose logging and development features
​
APP_ENV
string
default:"prod"
Application environment. Set to test to skip required environment variable validationOptions: prod, dev, test
​
LOG_LEVEL
string
default:"WARNING"
Logging verbosity levelOptions: DEBUG, INFO, WARNING, ERROR, CRITICAL

​
Database Settings

​
MONGODB_URI
string
default:"mongodb://localhost:27017"
required
MongoDB connection URIExample:
mongodb://localhost:27017
mongodb+srv://user:[email protected]/
​
MONGODB_DB
string
required
MongoDB database name for storing call data and tenant configurations
​
MONGODB_TRANSCRIPTS_COLLECTION
string
default:"calls-transcripts"
Collection name for storing call transcripts and conversation items
​
MONGODB_METADATA_COLLECTION
string
default:"calls-metadata"
Collection name for storing call metadata, summaries, and token metrics

​
OpenAI Settings

​
OPENAI_API_KEY
string
required
OpenAI API key for authenticationSecurity: This is a secret value. Store securely and never commit to version control.
​
OPENAI_PROJECT_ID
string
required
OpenAI project identifier for tracking usage and billing
​
OPENAI_BASE_URL
string
default:"https://api.openai.com/v1"
Base URL for OpenAI API. Change this to use a custom endpoint or proxy
​
OPENAI_SUMMARY_MODEL
string
default:"gpt-5-mini"
Model used for generating post-call summaries
​
OPENAI_WEBHOOK_SECRET
string
default:"changeme"
Secret for validating incoming webhooks from OpenAISecurity: Change this from the default value in production

​
Realtime Model Settings

​
OPENAI_SIP_MODEL
string
default:"gpt-realtime"
OpenAI Realtime model for SIP-based calls
​
OPENAI_WS_REALTIME_MODEL
string
default:"gpt-realtime-mini"
OpenAI Realtime model for WebSocket-based calls
​
OPENAI_WS_URL
string
default:"wss://api.openai.com/v1/realtime?"
required
WebSocket URL for OpenAI Realtime API
​
WS_SAMPLE_RATES
integer
default:"24000"
Audio sample rate in Hz for WebSocket connections
​
WS_CHUNK_SIZE
integer
default:"1024"
Audio chunk size in bytes for WebSocket streaming

​
Voice & Conversation Settings

​
DEFAULT_VOICE
string
default:"marin"
Default voice for the AI agentOptions: Check OpenAI Realtime API documentation for available voices
​
VOICE_SPEED
float
default:"1.0"
Speech speed multiplier. Range: 0.5 to 2.0
  • 1.0 = normal speed
  • < 1.0 = slower
  • > 1.0 = faster
​
MAX_OUTPUT_TOKENS
integer
default:"4096"
Maximum number of tokens in AI responses
​
TOOL_CHOICE
string
default:"auto"
Tool calling behavior for the AI agentOptions: auto, required, none
​
MAX_CONCURRENT_CALLS
integer
default:"100"
Maximum number of simultaneous active calls

​
Prompt Configuration

​
INSTRUCTIONS_FILE
string
default:"baseline.md"
Filename for the main instruction prompt in the prompts folderLocation: data/prompts/
​
GREETING_FILE
string
default:"greeting.md"
Filename for the greeting prompt in the prompts folderLocation: data/prompts/

​
Email Settings (SMTP)

​
SMTP_SERVER
string
default:"smtp.mail.me.com"
SMTP server hostname for sending emails
​
SMTP_PORT
integer
default:"587"
SMTP server port. Common values:
  • 587 = TLS (recommended)
  • 465 = SSL
  • 25 = unencrypted
​
SMTP_USER
string
SMTP authentication username
​
SMTP_PW
string
SMTP authentication passwordSecurity: This is a secret value. Store securely.
​
SMTP_FROM
string
Email address to use as sender for outgoing emails
​
SMTP_TO
string
Default recipient email address for summaries
​
SMTP_BCC
string
Blind carbon copy (BCC) recipient for all outgoing emails

​
API Endpoints

​
POST_CALL_URI
string
default:"http://127.0.0.1:8001"
URI for post-call processing webhook
​
CALLS_URI
string
default:"http://localhost:8000/"
Base URI for the calls API service

​
Authentication

​
ADMIN_TOKEN
string
default:"changeme"
Administrative API token for protected endpointsSecurity: Change this from the default value in production. This token provides full access to administrative functions.

​
Example .env File

# Environment
APP_ENV=prod
DEBUG=false
LOG_LEVEL=INFO

# Database
MONGODB_URI=mongodb+srv://user:[email protected]/
MONGODB_DB=sonore-phone-agent

# OpenAI
OPENAI_API_KEY=sk-proj-...
OPENAI_PROJECT_ID=proj_...
OPENAI_SUMMARY_MODEL=gpt-5-mini
OPENAI_WS_REALTIME_MODEL=gpt-realtime-mini
OPENAI_WS_URL=wss://api.openai.com/v1/realtime?

# Voice Settings
DEFAULT_VOICE=marin
VOICE_SPEED=1.0
MAX_OUTPUT_TOKENS=4096

# Call Management
MAX_CONCURRENT_CALLS=50

# Prompts
INSTRUCTIONS_FILE=baseline.md
GREETING_FILE=greeting.md

# Email
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PW=your-app-password
SMTP_FROM=[email protected]
SMTP_TO=[email protected]

# Security
ADMIN_TOKEN=your-secure-admin-token-here
OPENAI_WEBHOOK_SECRET=your-webhook-secret-here

# APIs
POST_CALL_URI=http://127.0.0.1:8001
CALLS_URI=http://localhost:8000/

​
Validation Rules

The following environment variables are required when APP_ENV is not set to test:
  • OPENAI_API_KEY
  • OPENAI_PROJECT_ID
  • OPENAI_WS_URL
If any required variable is missing, the application will fail to start with a ValueError listing the missing variables.

​
Accessing Settings in Code

Settings are accessible via the global settings object: 
from src.core.settings import settings

# Access configuration
db_uri = settings.mongodb_uri.get_secret_value()
model = settings.ws_realtime_model
max_calls = settings.max_concurrent_calls

# Computed fields
ws_endpoint = settings.ws_server_endpoint
Secret values (like API keys and passwords) are stored as SecretStr types. Use .get_secret_value() to access the actual string value.

Build docs developers (and LLMs) love

Get started for freeTalk to us