Skip to navigation
API ReferenceWidgets

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. See 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