Skip to main content

​
Voice Configuration

​
Multi-tenancy

Tenant configuration is database-backed via PostgreSQL, with an in-memory fallback for development. Cached tenant state is reused for performance and evicted when idle per TENANT_CACHE_IDLE_TTL_SECS (default 3600s). Reload cached tenants without dropping live sessions using POST /admin/tenants/reload-cached.

​
Auth transport

This is the setting most worth understanding before deploying.
LEGACY_QUERY_AUTH_ENABLED=true re-enables raw tenant tokens in query strings and Twilio custom-parameter bootstrap. It exists for migration scenarios and defaults to off.In NODE_ENV=production, startup fails fast when legacy auth is off but STREAM_AUTH_SECRET is unset — so a deployment cannot end up with neither transport working.
Rotate STREAM_AUTH_SECRET by setting the old value in STREAM_AUTH_SECRET_PREVIOUS, deploying the new secret, then removing the previous once in-flight tokens have expired.

​
Audio output

Per-tenant audio_output_provider: elevenlabs (default) or openai (explicit override). ElevenLabs transport and 5xx/429 failures retry with backoff, and a circuit breaker prevents a provider outage from cascading. Provider outcome metrics are emitted, and GET /admin/tenants/audio-providers shows configured vs effective provider along with fallback state and reason.

​
Provider base URLs

OPENAI_BASE_URL, ELEVENLABS_BASE_URL, and ELEVENLABS_WS_BASE_URL redirect Chat Completions, TTS, and STT traffic to an LLM gateway, regional proxy, or test harness. Defaults are the public provider hosts.
These are read once at startup. Changing them requires a restart.

​
Turn response mode

Controls how assistant replies reach TTS on the Chat Completions path: Resolution order: per-tenant turn_response_mode → process-wide TURN_RESPONSE_MODE → single_sentence.
The per-tenant field is settable live via the admin tenant-config PATCH, so you can roll streaming out tenant by tenant rather than flipping the whole fleet.

​
Voice activity detection

VAD tuning — threshold, prefix padding, silence — is set per tenant in tenant config. Values are clamped to safe defaults with a warning at load, so a bad value degrades rather than breaks.

​
Handoff workflows

receptionist.handoff_workflow drives number-specific bridge targets and post-call notes from tenant config rather than compiled code. twilio.human_agent_timeout_seconds (default 25s) bounds the ring on a human handoff. See Voice API for the no-answer recovery path.

​
Custom tools

Agent versions accept tools[] — a JSON-schema function plus your HTTPS endpoint. Mid-call invocations POST to your endpoint with Authorization passthrough and the webhook-style X-Webhook-Signature HMAC; the JSON reply becomes the tool result. POST /make-call also accepts a transient per-call config including tools, for prototyping without publishing an agent version.

​
Rate limiting

Per-IP and per-tenant token buckets with configurable limits and automatic cleanup. Tenant key extraction supports bearer auth, signed stream_token, and — only when explicitly enabled — legacy raw token transport.

​
Readiness gating

Kafka is probed and reported in /health/ready, but only fails readiness when HEALTH_READY_REQUIRE_KAFKA=true.
That default is deliberate: a broker outage cannot pull call-serving pods out of rotation. Enable it only if you genuinely want calls to stop when Kafka is down.

​
Admin safety

  • Admin tenant responses redact secrets; updates preserve existing values when you send the <redacted> placeholder.
  • Tenant reads expose deterministic config ETags, so writes can use If-Match to prevent lost updates.
  • ADMIN_API_KEY is required on admin routes via x-admin-key.