Place a web Call
A web Call connects a caller in a browser to an Agent. Your server starts the Call with its API key and hands the browser a participant token that is good for that one Call; the key never leaves your server.
On the Phase 0 host. Served since contracts 1.0.0. The commands on this page are examples; no CI job runs them yet (planned).
1. Create and publish an Agent
POST /v1/agents creates the editable draft. It needs a name, an engine, a language, and the transcriber, model and voice that name a Provider and a model each; GET /v1/providers lists what each Provider offers. The draft's other fields attach Tools, Policies, Knowledge bases, a Prompt template, an Outcome schema and a statechart, each covered by its own guide.
A Call runs a published version, never the draft. POST /v1/agents/{agent_id}/versions publishes the draft whose revision If-Match names; "activate": true makes the new version the one Calls run. POST /v1/agents/{agent_id}/publish-check answers what the publish would say without publishing.
2. Start the Call on your server
curl -X POST "$VOCAL_API/v1/calls" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"transport": "web", "agent_id": "agt_..."}'POST /v1/calls runs admission before any media exists, and answers 201 with the Call and its client object: url, token and expires_at. The token is a secret for this Call only. Hand the object to the browser, never log it, and let the browser join before expires_at.
Admission can refuse the Call, among others with 402 spend_cap_reached when the Organization's spend for the month has reached its cap, 409 agent_version_unavailable when the Agent has no version Calls can run, and 429 concurrency_limit_reached or, for a test key, test_daily_cap_reached. The operation page lists every answer.
3. Join from the browser
The browser joins the Call's LiveKit room at client.url with client.token, publishes the microphone and plays the Agent's audio. Any LiveKit browser client can do this. A Vocal browser package that wraps it, @vocalai/client-web, is built and not published.
4. Follow and end the Call
| What | Operation |
|---|---|
| The Call with its status and, once finalized, its Turn metrics | GET /v1/calls/{call_id} |
| Its events so far, identifiers and codes only | GET /v1/calls/{call_id}/events |
Its transcript; needs transcripts:read and is audited | GET /v1/calls/{call_id}/transcript |
End it with the reason canceled | POST /v1/calls/{call_id}/end |
The events arrive live on the events channel too; see Tools and the events channel. Once the Call is finalized, its Call trace explains each Turn.