Skip to main content
DispatchAI uses environment variables for all configuration. This guide documents every variable and its purpose.

​
Configuration File

All settings are stored in .env at the project root: 
# Copy the template
cp .env.example .env

# Edit with your values
vim .env
Never commit .env to version control. Sensitive credentials like API keys should be kept secure.

​
Required Variables

These variables are essential for core functionality:

​
Server Configuration

​
PORT
integer
default:"8000"
Port number for the uvicorn server.
.env
PORT=8000
Referenced in: app/core/config.py:6

​
Telnyx (Telephony Provider)

​
TELNYX_API_KEY
string
required
Telnyx REST API key for call control operations.
.env
TELNYX_API_KEY=KEY...
Where to get it:
  1. Log in to Telnyx Portal
  2. Navigate to API Keys under Settings
  3. Create a new API key with Call Control permissions
Used for:
  • Answering incoming calls (app/main.py:184)
  • Starting audio streams (app/main.py:202)
  • Text-to-speech greeting (app/main.py:190)
Referenced in: app/main.py:27, app/core/config.py:4
​
TELNYX_WEBHOOK_SECRET
string
required
Webhook signature secret for verifying incoming Telnyx events.
.env
TELNYX_WEBHOOK_SECRET=your_secret_here
This is optional during development but required in production to prevent webhook spoofing.
Referenced in: .env.example:6

​
Deepgram (Speech-to-Text)

​
DEEPGRAM_API_KEY
string
required
Deepgram API key for real-time transcription and batch audio processing.
.env
DEEPGRAM_API_KEY=your_deepgram_key
Where to get it:
  1. Sign up at Deepgram Console
  2. Create a new API key with Nova-2 model access
  3. Ensure sufficient credits for live streaming
Used for:
  • Live transcription via WebSocket (app/agents/stt_client.py)
  • Batch transcription of recorded calls (app/main.py:324-347)
  • Emotion sentiment analysis (app/agents/emotion.py:119-251)
Referenced in: app/main.py:29, app/agents/emotion.py:11

​
ngrok (Development Tunnels)

​
NGROK_AUTHTOKEN
string
required
ngrok authentication token for creating persistent public tunnels.
.env
NGROK_AUTHTOKEN=your_ngrok_token
Where to get it:
  1. Sign up at ngrok Dashboard
  2. Copy your authtoken from the Getting Started page
Why it’s needed: Telnyx webhooks require a public URL to send call events. In development, ngrok exposes your local server.Referenced in: app/core/config.py:5, scripts/dev_start.sh:23-44
​
HTTP_PUBLIC_URL
string
Override for the public HTTP URL (auto-detected from ngrok if not set).
.env
HTTP_PUBLIC_URL=https://your-domain.com
Use this in production when deploying to a fixed domain.Referenced in: .env.example:10
​
WS_PUBLIC_URL
string
Public WebSocket URL for Telnyx audio streaming.
.env
WS_PUBLIC_URL=wss://your-domain.com/ws
Auto-configured in dev mode: The dev_start.sh script automatically generates this from ngrok.Production setup: Point this to your WebSocket endpoint behind a reverse proxy (nginx, Caddy, etc.)Referenced in: app/main.py:28, app/main.py:206

​
Optional Variables

These enhance functionality but aren’t required:

​
OpenAI (LLM Services)

​
OPENAI_API_KEY
string
OpenAI API key for advanced emotion classification and call summarization.
.env
OPENAI_API_KEY=sk-...
Where to get it: OpenAI API KeysFallback behavior: If not set, DispatchAI uses heuristic-based emotion detection and simple transcript summaries.
  • Emotion: app/agents/emotion.py:254-331 (falls back to _analyze_emotion_heuristic)
  • Summary: app/agents/summary.py:14-38 (falls back to first-sentence extraction)
Referenced in: app/agents/emotion.py:9, app/agents/summary.py:6
​
OPENAI_MODEL_EMOTION
string
default:"gpt-5-nano"
OpenAI model for emotion classification.
.env
OPENAI_MODEL_EMOTION=gpt-4o-mini
Use faster/cheaper models like gpt-4o-mini for real-time classification.
Referenced in: app/agents/emotion.py:10

​
Provider Selection

​
EMOTION_PROVIDER
enum
default:"heuristic"
Choose the emotion detection provider.Options:
  • heuristic - Rule-based keyword matching (no API key required)
  • deepgram - Deepgram sentiment analysis
  • openai - OpenAI LLM classification
.env
EMOTION_PROVIDER=deepgram
Provider comparison:
ProviderSpeedAccuracyCostAPI Key Required
heuristic⚡️ InstantMediumFreeNo
deepgramFastHighLowDEEPGRAM_API_KEY
openaiSlowerHighestMediumOPENAI_API_KEY
Implementation: app/agents/emotion.py:334-351Referenced in: app/agents/emotion.py:8

​
Environment Settings

​
APP_ENV
enum
default:"dev"
Application environment mode.Options:
  • dev - Development mode with debug logging and in-memory storage
  • prod - Production mode (future: enables database persistence)
.env
APP_ENV=prod
Referenced in: app/main.py:82
​
DATABASE_URL
string
PostgreSQL connection string (future use).
.env
DATABASE_URL=postgresql://user:pass@localhost:5432/dispatchai
Currently unused. DispatchAI uses in-memory storage (InMemoryCallStore).
Referenced in: app/main.py:83
​
S3_BUCKET
string
S3 bucket name for storing call recordings (future use).
.env
S3_BUCKET=my-dispatchai-recordings
Referenced in: app/main.py:84

​
Configuration Loading

DispatchAI loads configuration using pydantic Settings:
app/core/config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    telnyx_api_key: str | None = None
    ngrok_authtoken: str | None = None
    port: int = 8000

    class Config:
        env_prefix = ""
        case_sensitive = False

settings = Settings()
Key features:
  • Case-insensitive: PORT, port, and Port all work
  • Type validation: Invalid types raise errors at startup
  • Automatic loading: Reads from .env via python-dotenv

​
ngrok Configuration

The ops/ngrok.yml file defines tunnel configuration:
ops/ngrok.yml
version: "2"
tunnels:
  api:
    addr: 8000
    proto: http
    inspect: false
  ws:
    addr: 8000
    proto: http
    inspect: false
This creates two tunnels to the same port:
  1. api tunnel - For HTTP webhook endpoints
  2. ws tunnel - For WebSocket audio streaming
Enable inspect: true to use ngrok’s web inspector at http://127.0.0.1:4040

​
Example Configurations

​
Minimal Development Setup

.env
# Minimum required for testing
PORT=8000
TELNYX_API_KEY=KEY...
NGROK_AUTHTOKEN=your_token
DEEPGRAM_API_KEY=your_key

​
Full Production Setup

.env
# Server
PORT=8000
APP_ENV=prod

# Telnyx
TELNYX_API_KEY=KEY...
TELNYX_WEBHOOK_SECRET=your_secret
HTTP_PUBLIC_URL=https://api.yourdomain.com
WS_PUBLIC_URL=wss://api.yourdomain.com/ws

# AI Services
DEEPGRAM_API_KEY=your_key
OPENAI_API_KEY=sk-...
EMOTION_PROVIDER=openai

# Storage (future)
DATABASE_URL=postgresql://...
S3_BUCKET=prod-recordings

​
Testing Without API Keys

.env
# Minimum for local testing (no real calls)
PORT=8000
EMOTION_PROVIDER=heuristic
# Skip TELNYX_API_KEY, DEEPGRAM_API_KEY, etc.
The system will fall back to mock/heuristic implementations.

​
Validation

To verify your configuration: 
# test_config.py
import os
from dotenv import load_dotenv

load_dotenv()

required = ['TELNYX_API_KEY', 'DEEPGRAM_API_KEY', 'NGROK_AUTHTOKEN']
missing = [k for k in required if not os.getenv(k)]

if missing:
    print(f"Missing required variables: {missing}")
else:
    print("✓ All required variables set")

​
Security Best Practices

Don’t commit .env files. Use platform secrets:
  • AWS: AWS Secrets Manager or Parameter Store
  • GCP: Secret Manager
  • Kubernetes: Sealed Secrets or External Secrets Operator
  • Docker: Docker secrets
Set up a rotation schedule:
  • Telnyx: Every 90 days
  • OpenAI: Every 180 days
  • Deepgram: Every 180 days
Always set TELNYX_WEBHOOK_SECRET in production to prevent spoofed events.
Use minimum required scopes:
  • Telnyx: Call Control only (no billing access)
  • OpenAI: Project-scoped keys
  • Deepgram: Read-only for on-premise deployments

​
Next Steps

Telephony Setup

Configure Telnyx webhooks and test your first call

Agent Configuration

Customize NLP agents and classification rules

Build docs developers (and LLMs) love

Get started for freeTalk to us