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

voice

web-call

Web Call

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/voice/web-call \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assistant_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "context_variables": {},
  "test_features": {
    "identity_resolution": false,
    "memory": false,
    "summarization": false,
    "extraction": false,
    "evaluations": false,
    "knowledge_gap_analysis": false
  }
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/voice/web-call"

payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assistant_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "context_variables": {},
    "test_features": {
        "identity_resolution": False,
        "memory": False,
        "summarization": False,
        "extraction": False,
        "evaluations": False,
        "knowledge_gap_analysis": False
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    assistant_revision_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    team_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    context_variables: {},
    test_features: {
      identity_resolution: false,
      memory: false,
      summarization: false,
      extraction: false,
      evaluations: false,
      knowledge_gap_analysis: false
    }
  })
};

fetch('https://api-sandbox.featherhq.com/v1/voice/web-call', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/voice/web-call",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'assistant_revision_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'team_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'context_variables' => [
        
    ],
    'test_features' => [
        'identity_resolution' => false,
        'memory' => false,
        'summarization' => false,
        'extraction' => false,
        'evaluations' => false,
        'knowledge_gap_analysis' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/voice/web-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/voice/web-call")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/voice/web-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "livekit_url": "<string>",
  "access_token": "<string>",
  "room_name": "<string>",
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "test_features": {
    "identity_resolution": true,
    "memory": true,
    "summarization": true,
    "extraction": true,
    "evaluations": true,
    "knowledge_gap_analysis": true,
    "version": 1
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

x-api-key

string

header

required

Body

application/json

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> | null

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

assistant_revision_id

string<uuid> | null

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> | null

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

Context Variables · object | null

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 · object | null

Optional test-session feature toggles (identity resolution, memory, summarization, extraction, evaluations, knowledge-gap analysis). Omitted / null resolves to all-off. Mirrors TestChatStartRequest.test_features.

Show child attributes

Response

Successful Response

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 · object

required

The resolved test-session feature snapshot for this call.

Show child attributes

Web Call

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/voice/web-call \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "assistant_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "context_variables": {},
  "test_features": {
    "identity_resolution": false,
    "memory": false,
    "summarization": false,
    "extraction": false,
    "evaluations": false,
    "knowledge_gap_analysis": false
  }
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/voice/web-call"

payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assistant_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "context_variables": {},
    "test_features": {
        "identity_resolution": False,
        "memory": False,
        "summarization": False,
        "extraction": False,
        "evaluations": False,
        "knowledge_gap_analysis": False
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    assistant_revision_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    team_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    context_variables: {},
    test_features: {
      identity_resolution: false,
      memory: false,
      summarization: false,
      extraction: false,
      evaluations: false,
      knowledge_gap_analysis: false
    }
  })
};

fetch('https://api-sandbox.featherhq.com/v1/voice/web-call', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/voice/web-call",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'assistant_revision_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'team_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'context_variables' => [
        
    ],
    'test_features' => [
        'identity_resolution' => false,
        'memory' => false,
        'summarization' => false,
        'extraction' => false,
        'evaluations' => false,
        'knowledge_gap_analysis' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/voice/web-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/voice/web-call")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/voice/web-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"assistant_revision_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"team_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"context_variables\": {},\n  \"test_features\": {\n    \"identity_resolution\": false,\n    \"memory\": false,\n    \"summarization\": false,\n    \"extraction\": false,\n    \"evaluations\": false,\n    \"knowledge_gap_analysis\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "livekit_url": "<string>",
  "access_token": "<string>",
  "room_name": "<string>",
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "test_features": {
    "identity_resolution": true,
    "memory": true,
    "summarization": true,
    "extraction": true,
    "evaluations": true,
    "knowledge_gap_analysis": true,
    "version": 1
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}