Skip to main content
Get your DispatchAI emergency triage system up and running quickly with this step-by-step guide.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.10 or higher installed
  • A Telnyx account with:
    • API key
    • A phone number configured for Call Control
  • ngrok account (free tier works) for public webhook URLs
  • Optional: Deepgram API key for speech-to-text
  • Optional: OpenAI API key for emotion classification

​
Installation

1

Clone the repository

git clone https://github.com/oseni99/dispatchai.git
cd dispatchai
2

Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3

Install dependencies

pip install -U pip
pip install -r requirements.txt
This installs FastAPI, uvicorn, and other core dependencies from requirements.txt:
fastapi>=0.95.0
uvicorn[standard]>=0.22.0
python-dotenv>=1.0.0
pydantic>=1.10.0
4

Configure environment variables

Copy the example environment file and edit it with your credentials:
cp .env.example .env
Edit .env and add your API keys:
# Required
TELNYX_API_KEY=your_telnyx_api_key
NGROK_AUTHTOKEN=your_ngrok_auth_token
PORT=8000

# Optional for enhanced features
DEEPGRAM_API_KEY=your_deepgram_api_key
OPENAI_API_KEY=your_openai_api_key
EMOTION_PROVIDER=heuristic  # or 'deepgram' or 'openai'
Never commit your .env file to version control. It’s already in .gitignore.
5

Start the development server

DispatchAI includes a startup script that launches both the FastAPI server and ngrok tunnels:
./scripts/dev_start.sh
This script:
  • Starts uvicorn on the port specified in your .env file (default: 8000)
  • Launches ngrok with two tunnels (HTTP for /api and WebSocket for /ws)
  • Writes the public URLs to ops/urls.txt
You should see output like:
INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.
6

Note your ngrok URLs

After startup, check ops/urls.txt for your public URLs:
cat ops/urls.txt
You’ll see something like:
HTTP: https://abc123.ngrok.io
WS: wss://def456.ngrok.io
These URLs change every time you restart ngrok (unless you have a paid account with reserved domains).
7

Configure Telnyx webhook

In your Telnyx portal:
  1. Go to Call Control Applications
  2. Select your application (or create one)
  3. Set the Webhook URL to: https://YOUR_HTTP_URL/api/v1/call/incoming
  4. Save the configuration
Update this webhook URL every time you restart ngrok in development.
8

Verify the setup

Check that the health endpoint is responding:
curl http://localhost:8000/health
Expected response:
{"status": "ok"}

​
Make Your First Call

Now you’re ready to test the system:
1

Call your Telnyx number

From any phone, call the phone number you configured in Telnyx.
2

Listen to the greeting

You’ll hear: “This is Dispatch AI. I’m listening. Please describe your emergency.”
3

Describe an emergency

Speak a sample emergency scenario, for example:
  • “Someone’s having a heart attack!”
  • “There’s a fire in the building!”
  • “I need help, someone broke into my house!”
4

Hang up to complete processing

When you hang up, DispatchAI will:
  • Transcribe the audio with Deepgram
  • Analyze emotion and distress
  • Classify the service type (EMS/FIRE/POLICE/OTHER)
  • Generate a summary
  • Calculate priority ranking
  • Add to the dispatch queue

​
View the Results

DispatchAI includes debug dashboards for development:

Live Calls Dashboard

Monitor active calls in real-time as they stream

Queue Dashboard

View the prioritized dispatch queue

​
Using the API

You can also query the API directly: 
# Get the current queue
curl http://localhost:8000/api/v1/queue

# Get recent calls
curl http://localhost:8000/api/v1/calls

# Get active calls
curl http://localhost:8000/api/v1/live_queue
Example queue response: 
[
  {
    "id": "call_abc123",
    "risk_level": "CRITICAL",
    "risk_score": 0.92,
    "category": "EMS",
    "tags": ["CARDIAC_ARREST", "UNCONSCIOUS"],
    "emotion": "HIGHLY_DISTRESSED",
    "summary": "Caller reporting unresponsive person, possible cardiac arrest",
    "status": "OPEN",
    "created_at": "2024-03-03T23:15:00Z",
    "from_masked": "••5678",
    "to": "+15551234567"
  }
]

​
Understanding the Results

Each processed call includes:
  • Risk Level: CRITICAL, ELEVATED, NORMAL, or LOW
  • Risk Score: Continuous 0-1 score based on distress + emotion
  • Category: EMS, FIRE, POLICE, or OTHER
  • Semantic Tags: Life-threatening indicators (CARDIAC_ARREST, ACTIVE_SHOOTER, etc.)
  • Emotion: CALM, TENSE, DISTRESSED, or HIGHLY_DISTRESSED
  • Summary: AI-generated description of the emergency
See the Core Concepts documentation to understand how these values are computed.

​
Troubleshooting

Problem: Telnyx isn’t triggering the webhook when you call.Solutions:
  • Verify ngrok is running: curl https://YOUR_HTTP_URL/health
  • Check the webhook URL in Telnyx exactly matches: https://YOUR_HTTP_URL/api/v1/call/incoming
  • Look for errors in the uvicorn terminal output
  • Check Telnyx portal logs for webhook delivery failures
Problem: Call connects but no audio analysis happens.Solutions:
  • Verify WS_PUBLIC_URL in .env matches your ngrok WebSocket URL (starts with wss://)
  • Check that your Telnyx Call Control app is configured for audio streaming
  • Look for WebSocket errors in the uvicorn logs
Problem: Audio processes but transcript is empty.Solutions:
  • Check that DEEPGRAM_API_KEY is set in .env
  • Verify your Deepgram account has credits
  • Ensure you spoke during the call (VAD requires voiced audio)
  • Check uvicorn logs for Deepgram API errors
Problem: Can’t execute the startup script.Solution:
chmod +x scripts/dev_start.sh
./scripts/dev_start.sh

​
Next Steps

Now that you have DispatchAI running, explore these topics:

Architecture

Understand how the system works

Configuration

Customize environment variables

Agent System

Learn about the AI agents

API Reference

Explore the REST API

Build docs developers (and LLMs) love

Get started for freeTalk to us