Initialize a client session
Exchange a client token for a browser chat session. Validates the token + request Origin, resolves the target flow or agent, and returns the session id plus widget display config. Pass an existing sessionId for legacy resume, or a visitor-authorized conversationId returned by the history list to reopen a conversation across sessions or verified devices.
Request
Response
The durable conversation record this session reads and writes. Returned by every successful branch — a fresh mint, a legacy sessionId replay, and a conversationId resume all report the record they landed on. Persist THIS rather than the session id: a session is short-lived, the conversation is what a returning browser reopens. It is not a credential; history access is still scoped by the visitor secret.
Opaque change token for conversationId at the moment this session was created. Compare it for equality and nothing else — it is unordered and unparseable. It changes on every transcript mutation, including a display-projection finalization that deliberately leaves updatedAt untouched, so a second device or a reloaded tab can tell whether the transcript it holds is still current.
ISO-8601 session idle-expiry timestamp.
The created (or resumed) client session ID.
Present instead of flow for a Runtype App token whose manifest declares record namespaces but no flows or agents. Exactly one of flow and app is returned.
Returned when the request negotiates durableRecovery. Older servers omit it; clients must then keep ordinary streaming behavior.
Resolved flow or agent for this session. Present on every response except the data-only Runtype App branch, which returns app instead. Retained for compatibility: id always carries the same value as the canonical top-level targetId, which new clients should read instead.
The flow or agent this session executes against, resolved server-side. Canonical replacement for flow.id, and the exact key to pass as targetId when listing or deleting this conversation’s history. Matches the value stored on the conversation record; an agent-only token resolves to its agent id. Absent only on the data-only Runtype App branch, which is not chat-capable.
The browser’s anonymous visitor identity. Present when the request opts into visitor history (or supplies a visitor token, identity proof, or conversation id). Authenticates the /client/conversations* history routes, which the site-wide client token alone cannot reach.