Get a widget session
One session in full: state, assertions, activity. The bearer token is never in the response.
wsess_… id or external_id:<value> form.
What info tells you
lastActiveAt is the field for “is this visitor still around”: token refreshes bump it even when no one is typing.
The token stays gone
spec.token is populated once, in the create response, and omitted on every read after. There is no recover-the-token endpoint. If the browser lost it, mint a new session and revoke the orphan.
Related
Revoke a widget session
Delete a widget session
List widget sessions
Create a widget session
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Session ID. Accepts the canonical wsess_… form or the external_id:<value> form.
Response
OK
WidgetSession is a delegated, narrowed credential for one visitor's use of a widget, minted server-to-server by the customer's backend. The session carries all customer-asserted context — tenant, subject, labels, secrets — and every conversation (objective) created through the widget inherits it. The bearer token returned at mint is short-lived and refreshed at the widget host; the session row is what makes revocation possible.
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
WidgetSessionSpec is the configuration of a session, fixed at mint.
The current lifecycle state of the session. Output only. Sessions are created STATE_ACTIVE; use :revoke to end one early.
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_EXPIRED, STATE_REVOKED, STATE_EXHAUSTED WidgetSessionInfo provides read-only server-derived data about a session.
Names of the secrets attached to the session. Values are write-only: provided at creation, encrypted at rest, and interpolated into tool-call headers server-side — never returned by any API.