Skip to main content
POST
Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules.

Request body

ThreadCreateRequest
string
Default: 'New conversation'.
string
Optional first visitor message.
string
Default: 'chat'.
ChatMeta
Free-form request metadata forwarded to the agent (department, custom fields, page context, sessionId, and agent/agentConfig/kb identity hints). Stored on the thread. Shape is merchant-defined.
Provider
Allowed values: 'openai', 'anthropic', 'gemini'.
Attachment[]
Maximum items: 5.

Response

object
string
required
string
required
32-character base64url capability; echo it as x-widget-thread-token.
Thread
required
Thread as serialized for clients: server-only fields (state, accessToken, owner, restoredFromClientHistory) are stripped.

Status codes

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.
Last modified on November 13, 2026