---
title: "Web Call"
method: POST
path: "/v1/voice/web-call"
tags: ["voice"]
---

# Web Call

`POST /v1/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.

## Request body

- WebCallRequest — Browser-initiated test call against an agent or team. Mints a short-lived LiveKit access token whose ``RoomConfiguration`` embeds an ``agent_dispatch`` directive — when the browser connects, the voice-worker is auto-dispatched into the freshly-created room. The server signs the selected principal into token metadata so the browser cannot tamper with what it is testing. Single-agent calls resolve the selected revision's bound workflow or open AgentNode fallback. Team calls pin the current active team revision and roster; an unpinned member's assistant revision resolves through the normal active-revision rule.
  - `agent_id` string, uuid, nullable — Agent whose VoicePipelineConfig drives the call. Provide this XOR `team_id`.
  - `assistant_revision_id` string, 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_id` string, 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_variables` object, 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).
  - `test_features` TestSessionFeatureInput — Caller-supplied toggles. Unknown fields are rejected.
    - `identity_resolution` boolean
    - `memory` boolean
    - `summarization` boolean
    - `extraction` boolean
    - `evaluations` boolean
    - `knowledge_gap_analysis` boolean

## Response `200`

Successful Response

- WebCallResponse
  - `livekit_url` string, required — wss:// URL the browser passes to livekit-client.connect().
  - `access_token` string, required — Short-lived (5 min) LiveKit JWT. Embeds RoomAgentDispatch so the voice-worker auto-joins when the browser connects.
  - `room_name` string, required
  - `session_id` string, uuid, required
  - `end_user_id` string, 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`.
  - `test_features` TestSessionFeatures, required — Resolved, immutable snapshot persisted on a test conversation.
    - `version` 1
    - `identity_resolution` boolean, required
    - `memory` boolean, required
    - `summarization` boolean, required
    - `extraction` boolean, required
    - `evaluations` boolean, required
    - `knowledge_gap_analysis` boolean, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/revisions/5a5597ebb2d6/schema)