How KlawVoice works

A tour of the pipeline behind a call, for engineers deciding whether to trust it.

The turn-based voice loop (default)

caller ⇄ Twilio ⇄ KlawVoice
  1. Twilio webhook (signature-verified) resolves the agent by dialed number
  2. Greeting spoken via ElevenLabs TTS (Polly fallback), listening starts
  3. Twilio speech recognition posts the caller's turn
  4. Knowledge retrieval (embeddings + pgvector, ≤1.2s budget)
  5. Reply generated — multiple LLM providers raced, first good answer wins (4.5s ceiling)
  6. Reply spoken; loop continues until hangup

Latency is engineered per stage: agent config is cached (60s), retrieval is skipped for short acknowledgements, prompt context is trimmed to the last six turns, replies are capped at one-two sentences for natural pacing, and time-to-first-token is recorded per turn.

Transcripts and insights

Every turn is appended atomically to the call record (JSONB append — safe under concurrency), so GET /api/v1/calls/{id} shows the conversation as it happens. When the call ends, a status callback computes the summary, sentiment, and intent, then emits call.ended, call.transcribed, and call.completed events.

The realtime bridge (optional)

Agents can opt into a streaming voice bridge: set the agent's runpod_url and its calls route to a dedicated realtime media server instead of the turn-based loop. The bridge self-registers its tunnel URL with the platform. Same personas, same transcripts, lower latency — at the cost of running bridge infrastructure.

Grounding

Knowledge documents are chunked and embedded at upload; per-turn retrieval runs a vector search and injects the best passages into the reply prompt. See Knowledge base.

Trust surface

Twilio webhooks are signature-verified; user webhooks are HMAC-signed and SSRF-guarded; API keys are stored only as hashes; public capability manifests are ed25519-attested (SMCP).

Machine-readable API spec: Swagger UI · /swagger.json.