SIP & Telephony
VoxBridge connects to the public telephone network through managed SIP trunks and real-time media infrastructure. Phase 2 enables live outbound dialing and inbound DID routing.
Architecture
- API queues calls in PostgreSQL and triggers webhooks.
- Dispatcher creates media sessions and SIP participants using trunk credentials.
- Agent worker joins the session, runs STT/LLM/TTS with your org agent prompt and voice.
- Carrier SIP carries PSTN audio between the phone network and the media layer.
Carrier connectivity
VOXBRIDGE uses production-grade SIP connectivity for phone numbers, call control, and trunk management. Enterprise plans can discuss dedicated trunks and custom carrier arrangements.
- Provision SIP credentials through your platform admin or environment configuration
- Set up an outbound voice profile for caller ID on proactive calls
- Purchase or port DIDs for inbound lines and verified outbound caller ID
- Map connection identifiers to VoxBridge environment variables
Set TELEPHONY_PROVIDER on the API service (default: platform-managed carrier).
Media & SIP trunks
The real-time media layer terminates SIP and bridges audio into agent sessions — whether cloud-hosted or self-managed.
- Outbound trunk — places calls to PSTN numbers from queued
Callrecords - Inbound trunk — accepts calls to your DIDs and dispatches to inbound agents
- Worker — Python agent in
workers/using the platform voice worker SDK
Environment variables
Add these to .env on the API host and worker nodes:
| Variable | Service | Description |
|---|---|---|
LIVEKIT_URL | API, worker | Media server WebSocket URL (e.g. wss://your-media.example) |
LIVEKIT_API_KEY | API, worker | Media server API key |
LIVEKIT_API_SECRET | API, worker | Media server API secret |
LIVEKIT_SIP_OUTBOUND_TRUNK_ID | API, worker | Outbound SIP trunk ID for outbound participants |
TELNYX_API_KEY | API | Carrier REST API key |
TELNYX_CONNECTION_ID | API | SIP connection / credential connection ID |
TELEPHONY_PROVIDER | API | Telephony provider label (platform default) |
API_PUBLIC_URL | API | Public base URL for callbacks and docs |
Outbound requirements
Once telephony is enabled, outbound calls require from (caller ID) on the API request — a verified number on your SIP connection. Without media server variables configured, calls stay in queued and dispatch returns:
Running the voice worker
Workers need the same media server URL, API key, and API secret as the API. Scale worker nodes horizontally for more concurrent calls (see server capacity docs).
Inbound setup (Phase 2)
- Configure inbound SIP trunk on your carrier connection
- Assign DID → organization mapping
- Ensure an active
direction: inboundagent exists - Test with a PSTN call to your number; verify agent answers with inbound prompt
Capacity planning
On a minimal 2 vCPU / 4 GB VPS, plan for roughly 2–4 concurrent voice sessions. API and webhook traffic scales to hundreds of tenants; voice concurrency is limited by worker RAM and SIP trunk CPS limits.