Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Voice

Start Test Call

Talk to the live voice agent from the browser, without a phone line (admin+). Creates a call clearly marked as a test (`is_test`, no phone number), dispatches the voice agent (`VOICE_LIVEKIT_AGENT_NAME`) into a new LiveKit room with the normal call metadata (the lead, persona, `language` (the one sent, else the lead's), provider overrides) and returns a participant token for the browser. Nothing is dialled: the telephony checks (consent, calling windows, caps) don't apply, and the call never counts toward the caps or analytics (no timeline events, suppressions, meetings, callbacks, tasks or AI analysis). At most `VOICE_TEST_CALLS_PER_DAY` (20) per workspace and UTC day (429 after). 503 without LiveKit.

API key access

Needs the admin scope with an API key (ro_pat_...). A signed-in session uses the caller's role.
POST/api/v1/voice/test-calls

Authorization

AuthorizationBearer <token>

Access token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).

In: header

Header Parameters

X-Workspace-Id?string | null

Id of the workspace to act on (must be a member).

Request Body

lead_idstring

The lead the agent "calls" (its name, company, memory and language are used; nothing is written to it).

Formatuuid
language?string | null

The call's language (en, te, hi-IN, ...); unset: the lead's, else the workspace's.

Lengthlength <= 35

Response Body

curl -X POST "http://localhost:8000/api/v1/voice/test-calls" \  -H "X-Workspace-Id: string" \  -H "Content-Type: application/json" \  -d '{    "lead_id": "9bddab70-98e6-43a9-8f32-c9788b9de0c0"  }'
{
  "call_id": "0d0a16ab-a508-4d58-bf24-5dc3cb248f3e",
  "lead_id": "9bddab70-98e6-43a9-8f32-c9788b9de0c0",
  "room": "string",
  "livekit_url": "string",
  "token": "string",
  "identity": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "agent_name": "string",
  "language": "string",
  "is_test": true,
  "remaining_today": 0
}
Empty
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
Empty
Empty
Empty

Schedule Callback

Flag the call for a callback. The free-text `preferred_time` is read in the lead's time zone and, when telephony is configured, an AI callback call is queued for then (compliance re-checked when it runs); otherwise the lead gets a task note for a human (RO-134).

Transfer Result

How the live warm transfer offered by ``/handoff`` went (RO-064). ``connected``: the teammate was briefed and joined the caller; the briefing goes on the lead's timeline. ``no_answer`` / ``busy`` / ``failed``: the handoff task note is added instead (also when the call ends without a report). Idempotent (``recorded: false`` once reported); 409 when no transfer was offered on this call.