Voice Platform
Real-time voice interaction with Norns AI agents.
Last updated: 2026-01-03
Overview
Norns supports two voice interfaces:
| Interface | Technology | Access |
|---|---|---|
| Web Voice | LiveKit + OpenAI Realtime | voice.ravenhelm.dev |
| Phone Voice | Twilio + Pipecat | +1 (737) 214-3330 |
Both interfaces delegate all actions to the Norns LangGraph agent.
Architecture
Services
| Service | Purpose | URL | Location |
|---|---|---|---|
| Voice Gateway | Web voice via LiveKit | voice.ravenhelm.dev | /services/voice-gateway/ |
| Telephony | Phone voice via Pipecat | telephony.ravenhelm.dev | /services/telephony/ |
| LiveKit | WebRTC infrastructure | wss://livekit.ravenhelm.dev | /services/livekit/ |
| Whisper | Speech-to-text (STT) | Internal (9000) | /services/whisper/ |
| Piper | Text-to-speech (TTS) | Internal (10200) | /services/piper/ |
Voice Pipeline (Phone)
The GPT-4o-mini acts as a lightweight router:
- Passes user requests verbatim to Norns via function
- Only handles simple greetings directly
- Keeps responses short (1-3 sentences) for natural conversation
Caller Identification
Phone callers are identified by their phone number (ANI):
- Twilio sends incoming call with caller's phone number
- Telephony service calls
- Norns looks up user by column in users table
- If found, uses that user's ID for the conversation
- If not found, uses default user ID
Adding a User's Phone Number
Quick Commands
{"status":"healthy","service":"telephony"}
Configuration
Voice Gateway (Web)
| Variable | Description |
|---|---|
| LiveKit server URL | |
| LiveKit API key | |
| LiveKit API secret | |
| OpenAI API key (for Realtime) |
Telephony (Phone)
| Variable | Description |
|---|---|
| Public hostname (telephony.ravenhelm.dev) | |
| Norns API URL (http://docs/AI-ML-Platform/norns-agent:8000) | |
| API key for Norns authentication | |
| Twilio account SID | |
| Twilio auth token | |
| Deepgram STT API key | |
| OpenAI API key (for GPT-4o-mini routing) | |
| ElevenLabs TTS API key | |
| ElevenLabs voice ID |
Security
- All traffic over HTTPS (Traefik TLS termination)
- Twilio webhook signed with account credentials
- Norns API protected by X-API-Key header
- No UDP ports exposed (Twilio Media Streams uses WebSocket)
Troubleshooting
Issue: Caller Not Identified
Symptoms: Phone call works but uses default user
Diagnosis:
Solution:
Issue: No Audio on Phone Call
Symptoms: Call connects but no audio
Diagnosis:
- Check telephony logs for WebSocket errors
- Verify Deepgram/ElevenLabs API keys are set
- Check Twilio Media Streams connection
Solution: Cannot connect to the Docker daemon at unix:///Users/nate/.docker/run/docker.sock. Is the docker daemon running?