Start a web call
Opens a browser voice call with an agent. Returns 202 with the call (id), a single-use grant, grant_expires_at and ice_servers; send the browser’s WebRTC offer before the grant expires. Send an Idempotency-Key. test_mode talks to the agent’s draft. To let the browser connect without your API key, set allowed_origin to the website it runs on (https://shop.example.com, no path; http://localhost works for development) and hand the browser only id, grant and ice_servers: it then uses the /client operations from that origin.
Scopes: webcall:create
Authorizations
An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.
Headers
A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.
255The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.
2026-11-07 "2026-11-07"
Body
The agent the browser talks to. It must be published (or test_mode).
Values for the agent's {{variables}} (e.g. first_name).
Your own data, stored with the call and sent back in its webhooks.
Your own reference for the call.
120A test call: it may use the agent's unpublished draft.
The website the browser will call from, as an origin: https://host[:port] with no path (http://localhost:<port> for development). With it, the browser can negotiate on the key-free /client operations using only the grant, from that origin only; without it, negotiate from your server with your API key.
300Response
Successful Response
A new browser call: the call, plus what the browser needs to connect.
The call's id (call_…).
phone, or web for a browser call.
phone, web Whether the agent answered it or made it.
inbound, outbound Where the call is now. completed, failed and canceled are final.
requested, queued, dialing, ringing, connected, ending, completed, failed, canceled How it ended; null while it is live.
answered, busy, no_answer, rejected, abandoned, provider_failed, runtime_failed, canceled, unknown A stop you asked for that the carrier hasn't confirmed yet.
none, cancel_requested, hangup_requested The review flag: needs_review until someone marks it reviewed.
none, needs_review, reviewed Bumped on every change. Send it back as If-Match on a write.
The agent on the call.
The agent version the call ran.
The external party, masked.
The external party's country (ISO 3166-1 alpha-2).
The person who placed it, if one did.
The team it belongs to, if any.
When it was requested (ISO 8601).
When it was answered (ISO 8601).
When it ended (ISO 8601).
How long it rang.
How long the conversation lasted.
Ringing plus talking.
Dial attempts made.
Why it ended, in a stable code.
An error code when it failed.
Whether the minutes used are final yet.
Whether the cost is final yet (complete once settled).
Whether every call event arrived.
A recording can be downloaded.
A transcript can be read.
The caller was moved to a person or number.
Where it was transferred to, masked.
How it was transferred.
When it was transferred (ISO 8601).
What this key may do to this call.
Whether the post-call analysis has run.
pending, running, complete, skipped, failed When the analysis ran (ISO 8601).
What the call achieved, e.g. booked or callback.
The caller's mood, from -1 (negative) to 1 (positive).
positive, neutral or negative.
A short summary. Null without call:content.
The caller's name, if they gave it. Null without call:content.
The caller's company. Null without call:content.
The caller's email. Null without call:content.
When the caller asked to be called back (ISO 8601).
Labels on the call.
Why it was flagged for review.
When it was marked reviewed (ISO 8601).
When it was archived (ISO 8601).
The call's cost in millionths of currency, once settled.
The cost's currency (ISO 4217), once settled.
The single-use grant the browser sends as X-Webcall-Grant. Keep it out of logs.
When the grant stops working if unused (ISO 8601).
STUN/TURN servers to give the browser's RTCPeerConnection.