Skip to main content

​
Overview

DispatchAI uses environment variables for all configuration. Variables are loaded from a .env file via python-dotenv at application startup.

​
Configuration File

Create a .env file in the project root: 
cp .env.example .env

​
Required Variables

​
Server Configuration

​
PORT
integer
default:"8000"
Port for the uvicorn server. Must match the port configured in ngrok tunnels.
​
APP_ENV
string
default:"dev"
Application environment. Valid values: dev, prodControls storage backend selection:
  • dev: Uses in-memory storage (data lost on restart)
  • prod: Currently uses in-memory storage (Postgres support planned)

​
Telephony (Telnyx)

​
TELNYX_API_KEY
string
required
Telnyx REST API key for call control operations.Obtain from: https://portal.telnyx.comUsed for:
  • Answering incoming calls
  • Starting audio streams
  • TTS greeting playback
Referenced in: app/main.py:27
​
TELNYX_WEBHOOK_SECRET
string
Optional webhook signature verification secret.Currently not enforced but recommended for production deployments.

​
Public URLs (ngrok)

​
NGROK_AUTHTOKEN
string
required
ngrok authentication token for persistent tunnels.Obtain from: https://dashboard.ngrok.comRequired for dev_start.sh to automatically start tunnels.
​
WS_PUBLIC_URL
string
required
Public WebSocket URL for Telnyx to stream audio frames.Format: wss://your-domain.ngrok.io/ws
This URL must be publicly accessible from Telnyx servers. Update this value whenever your ngrok tunnel URL changes.
Referenced in: app/main.py:28, app/main.py:206
​
HTTP_PUBLIC_URL
string
Public HTTP URL for webhook endpoints.Format: https://your-domain.ngrok.io

​
Speech-to-Text (Deepgram)

​
DEEPGRAM_API_KEY
string
required
Deepgram API key for speech transcription and sentiment analysis.Obtain from: https://console.deepgram.comUsed for:
  • Batch transcription of call recordings (Nova-2 model)
  • Real-time sentiment analysis via Text Intelligence API
Referenced in: app/main.py:29, app/agents/emotion.py:11

​
AI Models (OpenAI)

​
OPENAI_API_KEY
string
OpenAI API key for GPT-powered features.Obtain from: https://platform.openai.com/api-keysUsed for:
  • Call summary generation (gpt-4o-mini)
  • Emotion classification (optional, falls back to heuristic)
If not provided, the system falls back to heuristic-based summaries.Referenced in: app/agents/summary.py:6, app/agents/emotion.py:9
​
OPENAI_MODEL_EMOTION
string
default:"gpt-5-nano"
OpenAI model to use for emotion analysis when EMOTION_PROVIDER=openai.

​
AI Provider Selection

​
EMOTION_PROVIDER
string
default:"heuristic"
Emotion analysis provider. Valid values:
  • heuristic: Rule-based classifier using distress score + keyword matching (no API cost)
  • deepgram: Deepgram Text Intelligence sentiment API
  • openai: GPT-based emotion classification
Referenced in: app/agents/emotion.py:8

​
Database (Planned)

​
DATABASE_URL
string
PostgreSQL connection string.Format: postgresql://user:pass@host:5432/dbnameCurrently unused. The system uses in-memory storage via InMemoryCallStore.Referenced in: app/main.py:83

​
Storage (Planned)

​
S3_BUCKET
string
S3 bucket name for call recording storage.Currently unused. Call recordings are stored locally in data/recordings/.Referenced in: app/main.py:84

​
Example Configuration

​
Development

# Server
PORT=8000
APP_ENV=dev

# Telnyx
TELNYX_API_KEY=KEY01234567890abcdefABCDEF
TELNYX_WEBHOOK_SECRET=

# ngrok
NGROK_AUTHTOKEN=2abcdefGHIJKLMNOP_1234567890qrstuvwxyz
HTTP_PUBLIC_URL=https://abc123.ngrok.io
WS_PUBLIC_URL=wss://abc123.ngrok.io/ws

# Deepgram
DEEPGRAM_API_KEY=0123456789abcdef0123456789abcdef01234567

# OpenAI (optional)
OPENAI_API_KEY=sk-proj-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOP

# Providers
EMOTION_PROVIDER=deepgram

​
Production

# Server
PORT=8000
APP_ENV=prod

# Telnyx
TELNYX_API_KEY=KEY_prod_01234567890abcdefABCDEF
TELNYX_WEBHOOK_SECRET=whsec_prod_0123456789abcdef

# Public URLs (use your production domain)
HTTP_PUBLIC_URL=https://api.dispatchai.example.com
WS_PUBLIC_URL=wss://api.dispatchai.example.com/ws

# Deepgram
DEEPGRAM_API_KEY=prod_0123456789abcdef0123456789abcdef01234567

# OpenAI
OPENAI_API_KEY=sk-prod-abcdefghijklmnopqrstuvwxyz1234567890ABCDEF

# Providers
EMOTION_PROVIDER=deepgram

# Database (when implemented)
DATABASE_URL=postgresql://dispatchai:[email protected]:5432/dispatchai_prod

# Storage (when implemented)
S3_BUCKET=dispatchai-prod-recordings

​
Environment Variable Loading

Variables are loaded at application startup in app/main.py: 
from dotenv import load_dotenv
import os

load_dotenv()  # Loads .env file

TELNYX_API_KEY = os.getenv("TELNYX_API_KEY")
WS_PUBLIC_URL = os.getenv("WS_PUBLIC_URL")
DEEPGRAM_API_KEY = os.getenv("DEEPGRAM_API_KEY")
Security Note: Never commit .env files to version control. The .env.example file provides a template without sensitive values.

​
Configuration Validation

The application performs minimal validation at startup. Missing critical variables will cause runtime errors:
  • If TELNYX_API_KEY is missing: Call control operations will fail
  • If WS_PUBLIC_URL is missing: Audio streaming will not start
  • If DEEPGRAM_API_KEY is missing: Transcription will be skipped
  • If OPENAI_API_KEY is missing: Falls back to heuristic summaries

​
Runtime Configuration Changes

Environment variables are loaded once at startup. Changes to .env require an application restart to take effect.
To apply configuration changes: 
# Stop the server (Ctrl+C)
# Edit .env
vim .env

# Restart
./scripts/dev_start.sh

​
Troubleshooting

​
Variables not loading

Symptom: Configuration values are None or default values are used Solution:
  1. Verify .env file exists in project root
  2. Check file format (no spaces around =, one variable per line)
  3. Ensure no quotes around values unless part of the actual value
  4. Restart the application

​
ngrok tunnel URL changes

Symptom: Webhooks stop working after restart Solution:
  1. Check ngrok console output for new public URL
  2. Update WS_PUBLIC_URL in .env
  3. Update webhook URL in Telnyx portal dashboard
  4. Restart application

​
API key authentication failures

Symptom: 401 Unauthorized errors from external APIs Solution:
  1. Verify API key is valid and not expired
  2. Check for extra whitespace in .env values
  3. Confirm API key has required permissions
  4. Test API key directly with curl before debugging application

Build docs developers (and LLMs) love

Get started for freeTalk to us