Create a widget voice session

View as Markdown
Mints short-lived credentials for a browser voice conversation with the widget's agent: a signed WebSocket URL, and when available a WebRTC conversation token (preferred, for echo cancellation and noise removal; fall back to `signed_url` if WebRTC cannot connect). Only for widgets with `voice_enabled: true`. No request body; call it per click and do not cache the result. Credentials, origin check and limits are the same as `POST /widget/init`. It does not need a session. **Side effects.** Calls the voice engine to mint the credentials for the agent's voice profile. Minting records no usage by itself; the voice conversation that follows runs on the widget's agent. **Idempotency.** Each call mints fresh credentials; retrying is harmless, and unused URLs expire. **Access** - **Required scope:** None; `jl_` API keys are not used. The widget credential plus a matching `x-widget-parent-origin` authorise the call. - **Rate limit:** Widget public — 60 requests/min per IP, plus the widget's `rate_limit_rpm` per credential and 300 requests/min per workspace; the general limiter also counts 120 requests/min per IP. See [Rate limits](/rate-limits). - **Plan:** Available on every plan.

Headers

x-widget-api-keystringOptionalformat: "^[0-9a-f]{64}$"

Secret widget API key (plaintext_api_key from POST /api/widgets). Takes precedence over x-widget-id and wid. Send one of the three. Never expose it in a browser.

x-widget-idstringOptionalformat: "uuid"

Public widget id, the credential the embed script uses. Used when x-widget-api-key is absent.

x-widget-parent-originstringRequiredformat: "uri"

Origin of the page embedding the widget. Must match one of the widget’s allowed_origins; see POST /widget/init.

Query parameters

widstringOptionalformat: "uuid"
Public widget id as a query parameter. Used when neither header is present.

Response

Voice credentials.
dataobject

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
502
Bad Gateway Error
503
Service Unavailable Error