Skip to main content

​
Voice API

Interactive documentation is served by the running instance at /swagger-ui, with the OpenAPI 3.0 document at /api-docs/openapi.json.

​
Service

​
Calls

POST /make-call supports an Idempotency-Key with 24-hour replay protection, a transient per-call config (custom tools included) for prototyping, and persisted metadata.
Browser calls run the same media protocol and pipeline as phone calls, so anything configured for telephony — agents, tools, transfers, evals — applies unchanged.

​
Media stream authentication

The WebSocket handshake authenticates a tenant by Authorization: Bearer … or a short-lived signed ?stream_token=….
Raw tenant-token query transport is opt-in via LEGACY_QUERY_AUTH_ENABLED=true and exists for migration only. It defaults to off. Configure STREAM_AUTH_SECRET to issue signed stream_token values instead.In NODE_ENV=production, startup fails fast if legacy auth is off and STREAM_AUTH_SECRET is not configured — so you cannot accidentally deploy with neither.

​
Sessions and supervision

Supervisor actions: monitor, whisper, barge, escalate, end.

​
Functions and automations

​
Human handoff

/transfer-call dials a human with a bounded ring timeout (twilio.human_agent_timeout_seconds, default 25s). If nobody answers, /transfer-complete reconnects the caller to the AI with a message-taking greeting rather than Twilio’s default hangup. A failed background escalation likewise speaks a recovery prompt — counted by escalation_bridge_failed_total — instead of leaving the caller on a silent line.

​
Admin

Admin routes require ADMIN_API_KEY, passed as x-admin-key.
GET /metrics on the main port requires x-admin-key. The dedicated METRICS_PORT is unauthenticated and must be network-restricted.
Admin tenant responses redact secrets, and updates can preserve existing values by sending the <redacted> placeholder. Tenant reads expose deterministic config ETags, so writes can use If-Match to avoid lost updates.