API contracts - Vox Systems

This page documents the API contracts between VoxCore and external systems. Use this if you’re building your own orchestrator (replacing VoxBridge) or integrating VoxCore into an existing platform.

How VoxCore works

VoxCore is a stateless pipeline worker. It doesn’t store bots, users, or call history. For each call:

It fetches bot configuration from a URL you provide (VOXBRIDGE_CONFIG_URL)
It runs the voice pipeline (STT → LLM → TTS)
It persists and POSTs call results to the webhook_url from the config

You implement two endpoints:

Config endpoint — VoxCore calls this to get bot config at call start
Results webhook — VoxCore calls this to deliver call results at call end

1. Config endpoint (you implement)

VoxCore fetches bot configuration at the start of every call.

Request (VoxCore → your system)

GET {VOXBRIDGE_CONFIG_URL}/{bot_id}?caller_id={caller}&stream_id={stream}&connected_event={json}
X-VoxCore-Secret: {secret}

Parameter	Source	Description
`bot_id`	URL path from WebSocket route or dialout request	Which bot to load
`caller_id`	Dialler handshake or SIP headers	Customer phone number
`stream_id`	Dialler handshake	Unique call identifier from the dialler
`connected_event`	URL-encoded JSON	Full handshake payload from dialler, attach, or dialout request (CRM fields, call direction, etc.)
`X-VoxCore-Secret`	`.env` on fleet server	Shared secret for authentication

Response (your system → VoxCore)

Return 200 with the full bot config JSON. See Bot config schema for the complete field reference. Minimal example:

{
  "session_id": "uuid-you-generate",
  "webhook_url": "https://your-api.com/call-results",
  "system_prompt": "You are a helpful assistant...",
  "opening_message": "Hello! How can I help you today?",
  "stt": {
    "provider": "deepgram",
    "api_key": "your-deepgram-key",
    "model": "nova-3",
    "language": "en"
  },
  "llm": {
    "provider": "google",
    "api_key": "your-google-key",
    "model": "gemini-2.5-flash",
    "temperature": 0.7,
    "max_tokens": 256
  },
  "tts": {
    "provider": "elevenlabs",
    "api_key": "your-elevenlabs-key",
    "voice_id": "your-voice-id",
    "model": "eleven_flash_v2_5",
    "language": "en"
  }
}

Error responses:

Status	Meaning	VoxCore behavior
`200`	Config returned	Call proceeds
`404`	Bot not found	Call rejected, WebSocket closed
`503`	Outside active hours	Call rejected, WebSocket closed
Other	Error	Call rejected, WebSocket closed

The session_id you return must be unique per call. VoxCore uses it to correlate the results webhook back to this call. Generate a UUID.

2. Results webhook (you implement)

VoxCore POSTs call results when a call ends. The URL comes from webhook_url in the config response.

Request (VoxCore → your system)

POST {webhook_url}
Content-Type: application/json
X-VoxCore-Secret: {secret}

Payload

{
  "session_id": "uuid-from-config",
  "stream_id": "dialler-stream-id",
  "caller_id": "+919876543210",
  "from_number": "+911234567890",
  "call_duration_seconds": 141.1,
  "call_direction": "inbound",
  "disconnected_by": "customer",
  "transcript": [
    {"speaker": "bot", "text": "Hello! How can I help?", "ts": 2.1, "language": "en", "finalized": true, "stt": {"confidence": 0.97}},
    {"speaker": "customer", "text": "Hi, I have a question", "ts": 5.3, "language": "hi", "finalized": true},
    {"speaker": "bot", "text": "Sure, go ahead!", "ts": 7.8}
  ],
  "recording_url": "https://storage.example.com/recording.wav",
  "recording_key": "calls/session-id.wav",
  "post_call_analysis": {
    "disposition": "INTERESTED",
    "summary": "Customer asked about pricing..."
  },
  "qc_analysis": null,
  "was_transferred": false,
  "transfer_destination": "",
  "transfer_target": "",
  "transfer_reason": "",
  "transfer_method": "",
  "transfer_at": null,
  "transfer_failed_reason": "",
  "latency": {
    "stt_avg_ms": 450.0,
    "rag_avg_ms": 0.0,
    "tool_avg_ms": 0.0,
    "llm_avg_ms": 520.0,
    "tts_avg_ms": 200.0,
    "total_avg_response_ms": 1170.0
  },
  "events": [
    {"event": "connected", "ts": 0.0},
    {"event": "pipeline_started", "ts": 0.5},
    {"event": "opening_message_queued", "ts": 0.5},
    {"event": "disconnected", "ts": 141.0, "by": "customer"},
    {"event": "pipeline_finished", "ts": 141.1}
  ],
  "usage_metrics": [
    {"type": "llm", "processor": "GoogleLLMService", "model": "gemini-2.5-flash", "prompt_tokens": 8000, "completion_tokens": 150, "total_tokens": 8150, "cache_read_input_tokens": 7800, "cache_creation_input_tokens": 0, "cache": {"enabled": true, "status": "hit", "namespace": "live_prompt", "version": "v3", "reason": null}},
    {"type": "tts", "processor": "ElevenLabsTTSService", "model": "eleven_flash_v2_5", "characters": 450},
    {"type": "ttfb", "processor": "ElevenLabsTTSService", "ttfb_ms": 310.0}
  ],
  "pipeline_config": {
    "transport_type": "websocket",
    "stt_provider": "deepgram",
    "stt_model": "nova-3",
    "llm_provider": "google",
    "llm_model": "gemini-2.5-flash",
    "tts_provider": "elevenlabs",
    "tts_model": "eleven_flash_v2_5",
    "tts_voice_id": "your-voice-id",
    "tts_language": "en"
  }
}

Field reference

Core fields
Transcript
Analysis
Transfer
Metrics

Field	Type	Description
`session_id`	string	Session ID from config response
`stream_id`	string	Dialler-assigned call identifier
`caller_id`	string	Customer phone number
`from_number`	string/null	Outbound caller ID / DID used for the call
`call_duration_seconds`	float	Total call length in seconds
`call_direction`	string	`"inbound"` or `"outbound"`
`disconnected_by`	string	Who ended the call (see table below)
`transcript`	list	Conversation transcript (see Transcript tab)
`recording_url`	string	URL to call recording (WAV)
`recording_key`	string	S3 key for generating signed URLs

Each transcript entry:

Field	Type	Description
`speaker`	string	`"bot"` or `"customer"`
`text`	string	Transcribed/spoken text
`ts`	float	Seconds from call start
`language`	string/null	Detected/spoken language code
`finalized`	bool/null	Whether the STT segment is final
`stt`	dict/null	Provider STT metadata (e.g. confidence, Flux turn events)

Field	Type	Description
`post_call_analysis`	dict/null	LLM-generated analysis — schema defined by your `post_call_analysis_prompt`
`qc_analysis`	dict/null	QC check results — schema defined by your `qc_prompt`
`intents`	list	Detected intents (if configured)

Native transfer state, derived from call events at the end of the pipeline. Replaces the old phone_transfer field. See Transfer & escalation.

Field	Type	Description
`was_transferred`	bool	True only when a `transfer_sent` event fired and no later `transfer_failed` event invalidated it
`transfer_destination`	string	Where the call was transferred (number/URI/queue)
`transfer_target`	string	Configured target label/id
`transfer_reason`	string	Reason the bot transferred
`transfer_method`	string	`icallmate_reverse_transfer`, `livekit_sip_refer`, or `agent_desk`
`transfer_at`	float/null	Seconds from call start when transfer fired
`transfer_failed_reason`	string	Populated when a transfer attempt failed

Field	Type	Description
`latency`	object	Average response latency: `stt_avg_ms`, `rag_avg_ms`, `tool_avg_ms`, `llm_avg_ms`, `tts_avg_ms`, `total_avg_response_ms`
`latency_samples`	list	Per-turn latency measurements
`usage_metrics`	list	Per-turn token/character/TTFB usage and cache metadata (see below)
`events`	list	Timestamped call lifecycle events (see below)
`pipeline_config`	object	Which providers/models were used

`usage_metrics` entries

Each entry records usage for one pipeline step.

Field	Type	Description
`type`	string	`llm`, `tts`, `ttfb`, `post_call`, or `qc`. Callback extraction is emitted as `type=post_call` with `processor=callback_extraction`.
`processor`	string/null	Pipecat service class (or post-call stage) that produced the metric
`model`	string/null	Model identifier
`prompt_tokens`	int/null	LLM input tokens
`completion_tokens`	int/null	LLM output tokens
`total_tokens`	int/null	LLM total tokens
`cache_read_input_tokens`	int/null	Tokens served from cache (cache read)
`cache_creation_input_tokens`	int/null	Tokens written when creating/refreshing a cache
`cache`	dict/null	Cache metadata (see below)
`characters`	int/null	TTS character count (TTS only)
`ttfb_ms`	float/null	Time-to-first-byte in ms (TTFB only)

The cache dict:

Key	Type	Description
`enabled`	bool	Whether caching was active for this step
`status`	string	`hit` / `miss` for live LLM; cache create/reuse status for post-call
`namespace`	string	`live_prompt` (first live `llm` entry), `post_call_analysis`, `qc_analysis`, or `callback_extraction`
`version`	string	Cache version in effect
`reason`	string/null	Why the cache was in this state (e.g. recreated/expired)

For OpenAI, live-prompt hit/miss is derived only from real cache_read_input_tokens (hit when > 0, miss when 0). VoxCore does not estimate cached tokens or money saved. Gemini/Vertex cache-creation tokens come from the provider’s cache usage metadata. See Caching.

`events` entries

events is an open-ended list of timestamped lifecycle entries. Every entry has event (string) and ts (float, seconds from call start). Depending on the event type, additional keys may be present:

Field	Description
`by`	Actor for disconnect events (`customer`, `bot`, …)
`trigger`	Hangup trigger: `end_call_tool`, `closure_phrase`, `dead_air_timeout`, `max_duration`
`function`	Tool name for tool-call events (`end_call`, `transfer_call`, `detected_voicemail`, `custom`)
`args`	Arguments passed to the tool
`status`	Tool status, e.g. `ok` / `no_number_configured`
`transfer_number` / `transfer_headers`	Transfer destination and SIP headers
`reason`	Human-readable reason (e.g. SIP failure description)
`sip_code` / `sip_status`	SIP response code and status text
`error`	Error string or dict (service errors)
`duration_ms` / `duration_seconds` / `raw_duration_seconds` / `billable_duration_seconds`	Duration fields
`note`	Free-form note

`disconnected_by` values

Value	Meaning
`bot`	Bot called end_call tool, closure phrase, or dead air timeout
`customer`	Customer hung up
`voicemail`	Voicemail detected
`RNR`	Dead air — customer picked up but stayed silent
`outside_hours`	Call rejected — bot outside active hours
`no_answer`	SIP 408/480 — callee didn’t answer (outbound only)
`rejected`	SIP 486/603 — callee rejected (outbound only)
`timeout`	Max call duration exceeded
`transfer_to_agent`	Call handed off to Agent Desk; route timeout must not tear it down
`error`	Pipeline startup failure or unhandled exception

Your response

Return 200 to acknowledge. VoxCore first writes results to a local durable outbox, then attempts delivery. Transient transport failures and 5xx responses are retried immediately a few times; any failed delivery attempt remains in the outbox and the background worker retries later.

3. Dialout endpoint (on VoxCore)

Trigger outbound calls by POSTing to VoxCore’s dialout endpoint. This requires LiveKit SIP to be configured on the fleet server.

Request (your system → VoxCore)

POST https://fleet.example.com/livekit/dialout
Content-Type: application/json
X-VoxCore-Secret: {secret}

{
  "bot_id": "your-bot-id",
  "to_number": "+919876543210",
  "from_number": "+911234567890",
  "connected_event": {
    "customer_name": "Rahul Sharma",
    "loan_number": "LN123456",
    "amount_due": "15000"
  },
  "config_url": "https://your-api.com/api/v1/config"
}

Field	Type	Required	Description
`bot_id`	string	Yes	Bot ID passed to config endpoint
`to_number`	string	Yes	Customer phone number to dial
`from_number`	string	No	Caller ID / DID. Uses default trunk number if omitted.
`connected_event`	dict	No	CRM data available as `{{call.field}}` in prompts
`config_url`	string	No	Override config endpoint URL. Falls back to `VOXBRIDGE_CONFIG_URL` env var.

The VoxCore dialout body uses connected_event. variables is a VoxBridge-only alias — VoxBridge maps variables to connected_event before proxying to VoxCore. When calling VoxCore directly, send connected_event.

config_url lets a shared VoxCore fleet serve multiple orchestrators. Each orchestrator passes its own config URL so VoxCore fetches the right bot config.

Response

{
  "status": "accepted",
  "call_id": "abc123-def456",
  "room_name": "dialout-abc123-def456"
}

Status	Body	Meaning
`200`	`{"status":"accepted","call_id":...,"room_name":...}`	Call accepted (runs in background)
`403`	`{"error":"Unauthorized"}`	Invalid `X-VoxCore-Secret`
`429`	`{"error":"At capacity"}`	Worker has no free call slot
`503`	`{"error":"LiveKit not configured"}`	LiveKit SIP not configured on this fleet host

The call runs asynchronously. Results are delivered via the webhook URL from the config response.

For campaign dialing, VoxDialler usually creates and screens the LiveKit SIP call first, then calls VoxCore POST /attach after the callee answers. Use /livekit/dialout for direct one-off VoxCore outbound calls.

Sequence diagram

Inbound calls (WebSocket)

For inbound WebSocket calls, the dialler connects directly to VoxCore:

wss://fleet.example.com/ws/{bot_id}

See WebSocket protocol for the handshake and message format. The same config fetch and results webhook flow applies — VoxCore calls your config endpoint at call start and your webhook at call end.

​How VoxCore works

​1. Config endpoint (you implement)

​Request (VoxCore → your system)

​Response (your system → VoxCore)

​2. Results webhook (you implement)

​Request (VoxCore → your system)

​Payload

​Field reference

​usage_metrics entries

​events entries

​disconnected_by values

​Your response

​3. Dialout endpoint (on VoxCore)

​Request (your system → VoxCore)

​Response

​Sequence diagram

​Inbound calls (WebSocket)

How VoxCore works

1. Config endpoint (you implement)

Request (VoxCore → your system)

Response (your system → VoxCore)

2. Results webhook (you implement)

Request (VoxCore → your system)

Payload

Field reference

`usage_metrics` entries

`events` entries

`disconnected_by` values

Your response

3. Dialout endpoint (on VoxCore)

Request (your system → VoxCore)

Response

Sequence diagram

Inbound calls (WebSocket)