Create widget session
Returns a short-lived token and the WebSocket path for the web widget of one of your agents. Your server asks for it with its API key and hands it to the widget, so the key never reaches the browser. The token is valid for 120 seconds and only for this agent; it is not single-use, so keep it private. A session is refused when the organization is suspended, when the web channel is not in the plan, when the minutes of the plan are used up and when the agent is suspended. The number of sessions opened per minute is also limited for the whole organization. With a test key the checks run but the token is not real: it starts with simulated_ and the WebSocket rejects it. Required scope: widget:session. This operation consumes usage (minutes, SMS or model calls) and is billed to the organization. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.
Authentication
Headers
API version for this request; defaults to the version the key is pinned to.
A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.
Request
Id of the agent the widget talks to, as returned by GET /agents. It must be an agent of the organization, and not suspended.
Response
Always widget_session.
A short-lived token for the web widget WebSocket. With a test key it is simulated_… and the WebSocket rejects it.
true when the request was made with a test key: the checks ran but the token is not real. false with a live key.