At the start of every call, VoxCore fetches the bot configuration from VoxBridge. The config defines the system prompt, service providers, voice settings, tools, and post-call behavior.
Config fetch
GET {VOXBRIDGE_CONFIG_URL}/{bot_id}?caller_id={caller}&stream_id={call_id}
X-VoxCore-Secret: {secret}
200 with the config JSON, 503 if the bot is outside active hours, or 404 if the bot doesn’t exist.
Schema reference
Top-level fields
| Field | Type | Default | Description |
|---|
session_id | string | (required) | Unique session identifier |
bot_id | string | "" | Bot identifier (used for KB context and logging) |
webhook_url | string | (required) | URL for results webhook |
system_prompt | string | (required) | LLM system prompt |
opening_message | string | (required) | First message bot speaks |
timezone | string | "UTC" | Timezone for timestamps |
re_engagement | object/null | null | Optional silence re-engagement config. Off by default (see below). |
min_words_interruption | int | 3 | Min words before customer can interrupt bot |
max_call_duration_seconds | int | 600 | Max call length before auto-hangup |
voicemail_message | string | "" | Message to speak when voicemail is detected |
pre_transfer_message | string | "" | Message to speak before call transfer |
tools | list[object] | [] | OpenAI-format tool definitions |
conversation_policy | dict/null | null | Structured policy that drives the policy engine (rules, flow, disposition schema). When null, the manual system_prompt is used. |
transfer_numbers | dict | {} | Map of name → phone number for transfers |
transfer_targets | list[object] | [] | Structured transfer targets for SIP, phone, WebSocket reverse-transfer, or Agent Desk handoff |
post_call_analysis_prompt | string | null | Prompt for post-call LLM analysis |
post_call_cache_enabled | bool | false | Enables explicit LLM caching for post-call analysis/QC prompts |
post_call_cache_version | string | "" | Cache version computed by VoxBridge from raw prompt templates; bump to invalidate |
post_call_cache | dict/null | null | Provider/cache hints for post-call caching |
qc_prompt | string | null | Prompt for QC analysis |
auto_dispositions | dict | null | Per-bot disposition overrides |
agent_desk_enabled | bool | false | Enables Agent Desk handoff behavior when transfer targets use agent_desk |
agent_desk_context | dict | {} | Extra context passed with Agent Desk handoffs |
callback_detection_enabled | bool | false | Enables mid-call callback-request detection and post-call extraction |
knowledge | object | disabled | Knowledge Base RAG runtime config |
ambient_sound | object | disabled | Optional ambient sound config |
sip_context | object | {} | SIP headers, variables, and transfer headers |
call_context | object | {} | Per-call variables available to runtime tools |
crm_context | dict | {} | CRM field values available to the custom-tool runtime |
prompt_parts | object/null | null | Direct-prompt live-cache config (see below) |
live_prompt_cache_state | object/null | null | Runtime live-cache handle passed back by VoxBridge (see below) |
STT config (stt)
| Field | Type | Default | Description |
|---|
provider | string | (required) | "deepgram", "deepgram_flux", or "soniox" |
api_key | string | "" | Provider API key |
model | string | "stt-rt-v4" | Model identifier |
language | string | "hi" | Language code |
extra | dict | {} | Provider-specific settings |
extra keys:
| Provider | Keys |
|---|
deepgram | endpointing, smart_format, punctuate, interim_results |
deepgram_flux | eot_threshold, eager_eot_threshold, eot_timeout_ms, keyterm, min_confidence, language_hints, should_interrupt |
soniox | language_hints, language_hints_strict, context, enable_speaker_diarization, enable_language_identification, client_reference_id, vad_force_turn_endpoint |
LLM config (llm)
| Field | Type | Default | Description |
|---|
provider | string | (required) | "openai", "google", or "google_vertex" |
api_key | string | "" | Provider API key |
model | string | (required) | Model identifier (e.g., "gemini-2.5-flash") |
temperature | float | 0.7 | Sampling temperature |
max_tokens | int | 256 | Max output tokens per turn |
extra | dict | {} | Provider-specific: top_p, top_k, frequency_penalty, presence_penalty, project_id (Vertex), location (Vertex) |
Google Vertex AI requires project_id in llm.extra. Calls fail at startup without it. location defaults to us-east4 if omitted.
TTS config (tts)
| Field | Type | Default | Description |
|---|
provider | string | (required) | "elevenlabs" or "sarvam" |
api_key | string | "" | Provider API key |
voice_id | string | (required) | Voice identifier |
model | string | null | Model identifier (e.g., "eleven_flash_v2_5") |
language | string | "en" | Language code |
extra | dict | {} | Provider-specific: speed, stability, similarity_boost, pitch, loudness, pace |
cache_config | object/null | null | Optional ElevenLabs Redis-backed audio cache config (see below) |
TTS cache config (tts.cache_config)
Redis-backed audio cache for ElevenLabs. Both snake_case and camelCase keys are accepted (camelCase aliases shown in parentheses).
| Field | Type | Default | Description |
|---|
enabled | bool | false | Enables the cache for this bot |
max_entries (maxEntries) | int | 5000 | Max cached entries (1–100000) |
ttl_sec (ttlSec) | int | 604800 | Entry TTL in seconds (60 – 90 days) |
max_text_len (maxTextLen) | int | 500 | Max text length eligible for caching (1–10000) |
get_timeout_ms (getTimeoutMs) | int | 100 | Cache lookup timeout in ms (1–5000) |
The cache requires TTS_CACHE_REDIS_URL to be set on the fleet host. When disabled (or unset), the normal ElevenLabs path is used.
VAD config (vad)
| Field | Type | Default | Description |
|---|
confidence | float | 0.7 | VAD confidence threshold |
start_secs | float | 0.2 | Seconds of speech to trigger start |
stop_secs | float | 0.2 | Seconds of silence to trigger stop |
min_volume | float | 0.6 | Minimum volume threshold |
Re-engagement config (re_engagement)
| Field | Type | Default | Description |
|---|
messages | list[string] | (required) | Prompts to speak when customer is silent |
gap_seconds | int | list[int] | 5 | Seconds before re-engagement. List = [first, subsequent]. |
max_retries | int | 2 | Max re-engagement attempts before RNR hangup |
re_engagement is optional and null by default — silence re-engagement is off unless VoxBridge sends this object.
Live prompt cache config (prompt_parts)
Direct-prompt live caching splits the live system prompt into a cacheable static part and a per-call dynamic part. See Caching for the full design.
| Field | Type | Default | Description |
|---|
mode | string | "legacy" | Prompt mode. "legacy" uses system_prompt; split-prompt modes use the fields below. |
cache_enabled | bool | false | Enables live prompt caching for this call |
static_system_prompt | string | "" | Static, cacheable portion of the prompt (policy, rules, schema) |
dynamic_runtime_prompt | string | "" | Per-call dynamic portion (customer vars, CRM fields, dates) |
static_version | string | "" | Version of the static prompt; controls cache reuse/invalidation |
openai_prompt_cache_key | string | "" | OpenAI prompt_cache_key hint for prefix routing |
openai_prompt_cache_retention | string | "in_memory" | OpenAI prompt_cache_retention hint |
Live prompt cache state (live_prompt_cache_state)
Runtime handle for an already-created Gemini/Vertex CachedContent, passed by VoxBridge so a warm cache can be reused across calls.
| Field | Type | Default | Description |
|---|
cache_name | string/null | null | Provider cache resource name |
expires_at | datetime/null | null | Cache expiry; VoxCore recreates the cache instead of failing the call when expired |
MinIO config (minio)
| Field | Type | Default | Description |
|---|
endpoint | string | "localhost:9000" | S3-compatible endpoint |
access_key | string | "minioadmin" | Access key |
secret_key | string | "minioadmin" | Secret key |
bucket | string | "recordings" | Bucket name |
secure | bool | false | Use HTTPS |
When minio is null in config, the worker falls back to environment variable MinIO settings. Set it explicitly in bot config to use a different storage destination per bot.
Knowledge config (knowledge)
| Field | Type | Default | Description |
|---|
enabled | bool | false | Enables the built-in search_knowledge tool |
bot_id | string | "" | Bot ID used for VoxBridge search context |
kb_ids | list[string] | [] | Attached knowledge-base IDs |
knowledge_bases | list[object] | [] | Attached KB summaries injected into the tool description |
top_k | int | 4 | Number of chunks to retrieve |
score_threshold | float | 0.55 | Minimum score for usable chunks |
strict | bool | true | If true, the bot should not answer outside approved KB results |
fallback_message | string | default refusal | Message when no approved result is found |
trigger_instructions | string | "" | Per-bot guidance for when to use RAG |
search_url | string | "" | VoxBridge search endpoint |
| Field | Description |
|---|
x_vox_timing.policy | immediate, speak_then_run, speak_and_run_parallel, terminal_after_speech, run_then_speak, or streaming_result |
x_vox_timing.pre_message | Guidance for the LLM-generated spoken pre-message |
x_vox_execution.kind | noop or http |
x_vox_execution.url | HTTP endpoint for kind=http |
x_vox_execution.method | HTTP method, default POST |
x_vox_execution.headers / params / json | Request templates. Supports {{args.*}}, {{call.*}}, {{sip.headers.*}}, and {{sip.variables.*}}. |
x_vox_execution.timeout_seconds | HTTP timeout, default 8 |
end_call, transfer_call, detected_voicemail, search_knowledge) are excluded from the custom runtime map.