Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-126178842.7 MB

5a5597ebb2d6

voice

Web Call

Mint a LiveKit access token + auto-dispatch directive for a browser call.

The browser passes the returned access_token to livekit-client's connect(livekit_url, access_token). LiveKit creates the room and auto-dispatches the voice-worker into it. The selected agent-or-team binding is JWT-signed and tamper-proof. A single-agent call uses the agent's active revision, or assistant_revision_id when the caller pins a draft; a team call pins the current active team revision and its roster. An unpinned member still follows that member's active assistant revision when the call's turn plan resolves. The session is created with session_type="test" so post-processing is gated by test_features (see src.conversation.test_features).

This route is reachable by an org-scoped API key (unlike /test-chat, which is dashboard/Clerk-only) — it depends only on Permission.RUNTIME_EXECUTE. So identity resolution + policy is resolved HERE, in the router, rather than in the voice service, which is deliberately auth-free: resolve_test_features raises ValidationError (422) up front for a bad/team-incompatible request, and select_test_session_end_user raises ValidationError (422) when identity_resolution=true and the caller (e.g. an API key) has no clerk_user_id — both short-circuit before any LiveKit work.

post/v1/voice/web-call

Request body

agent_idstring uuid nullable

Agent whose VoicePipelineConfig drives the call. Provide this XOR team_id.

assistant_revision_idstring uuid nullable

Optional: pin a specific revision for this test call (draft testing) instead of following the agent's active revision. Only valid alongside agent_id; must belong to that agent. Mirrors TestChatStartRequest.assistant_revision_id so a draft can be exercised over voice and chat without promoting it.

team_idstring uuid nullable

Team to test against — the team-level VoicePipelineConfig drives the call and the team's default active agent (initial member) answers/greets. Provide this XOR agent_id.

context_variablesobject nullable

Optional seed values for the bound agent's typed context variables, applied once at session bootstrap (same contract as the outbound-call door). Unknown key / uncoercible value → 422. Single-agent bindings only in v1 (ignored for team-bound test calls).

Response

Successful Response

livekit_urlstring required

wss:// URL the browser passes to livekit-client.connect().

access_tokenstring required

Short-lived (5 min) LiveKit JWT. Embeds RoomAgentDispatch so the voice-worker auto-joins when the browser connects.

room_namestring required
session_idstring uuid required
end_user_idstring uuid required

The EndUser this call's conversation is bound to. A throwaway random id when test_features.identity_resolution is false; the caller's resolved internal:<clerk_user_id> EndUser when true. Parity with TestChatStartResponse.end_user_id.