Skip to main content
This guide walks you through setting up DispatchAI from scratch, including dependencies, environment configuration, and running your first emergency call triage.

​
Prerequisites

Before starting, ensure you have:
  • Python 3.10+ installed
  • Git for cloning the repository
  • Active accounts for:

​
Installation

1

Clone the repository

Clone DispatchAI to your local machine:
git clone https://github.com/oseni99/dispatchai.git
cd dispatchai
2

Create a virtual environment

Set up an isolated Python environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3

Install dependencies

Upgrade pip and install required packages:
pip install -U pip
pip install -r requirements.txt
Core dependencies:
  • fastapi>=0.95.0 - Web framework
  • uvicorn[standard]>=0.22.0 - ASGI server
  • python-dotenv>=1.0.0 - Environment variable management
  • pydantic>=1.10.0 - Data validation
4

Copy environment template

Create your local configuration file:
cp .env.example .env
The template includes all required variables (see Configuration for details).
5

Configure API keys

Edit .env and add your API credentials:
.env
# Telnyx (required for phone calls)
TELNYX_API_KEY=KEY...
TELNYX_WEBHOOK_SECRET=your_webhook_secret

# ngrok (required for local development)
NGROK_AUTHTOKEN=your_ngrok_token

# Deepgram (required for transcription)
DEEPGRAM_API_KEY=your_deepgram_key

# OpenAI (optional, falls back to heuristics)
OPENAI_API_KEY=sk-...

# Server configuration
PORT=8000
Never commit .env to version control. The file is included in .gitignore by default.

​
Starting the Server

​
Development Mode (with ngrok)

The quickest way to get started is using the dev startup script, which launches both the FastAPI server and ngrok tunnels: 
./scripts/dev_start.sh
This script:
  1. Loads environment variables from .env
  2. Starts uvicorn on the configured port (default: 8000)
  3. Launches ngrok with two tunnels (API and WebSocket)
  4. Prints the public ngrok URL for webhook configuration
Expected output: 
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://0.0.0.0:8000
ngrok public URL: https://abc123.ngrok.io

​
Manual Start (without ngrok)

For production or custom deployments, start uvicorn directly: 
uvicorn app.main:app --host 0.0.0.0 --port 8000
Without ngrok, you’ll need to manually configure public URLs for Telnyx webhooks. See Telephony Setup.

​
Verify Installation

1

Check health endpoint

Confirm the server is running:
curl http://localhost:8000/health
Expected response:
{"status": "ok"}
2

Access debug interface

Open the live calls dashboard in your browser:
http://localhost:8000/debug/live_calls/
You should see an empty call list with “Polling /api/v1/live_queue every 1s.”
3

Test webhook endpoint

Verify the Telnyx webhook handler is accessible:
curl -X POST http://localhost:8000/api/v1/call/incoming \
  -H "Content-Type: application/json" \
  -d '{"data": {"event_type": "test"}}'
Expected response:
{"status": "ok"}

​
Next Steps

Configuration

Learn about environment variables and advanced configuration options

Telephony Setup

Configure Telnyx integration and test your first call

Agent Configuration

Customize NLP, emotion detection, and service classification

API Reference

Explore REST endpoints and WebSocket handlers

​
Troubleshooting

​
Port Already in Use

If port 8000 is occupied: 
# Change port in .env
echo "PORT=8001" >> .env

# Or override at runtime
PORT=8001 ./scripts/dev_start.sh

​
ngrok Connection Failed

Verify your authtoken is correct: 
ngrok config check
Manually test ngrok: 
ngrok http 8000

​
Import Errors

Ensure virtual environment is activated: 
source .venv/bin/activate
pip install -r requirements.txt

​
API Key Issues

Check that .env is loaded correctly: 
import os
from dotenv import load_dotenv

load_dotenv()
print(os.getenv('TELNYX_API_KEY'))  # Should print your key
Refer to the Configuration Guide for detailed environment variable documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us