POST
Start a Support Session

Overview

Starts a support session in one request: it mints a short-lived SDK token and creates (or reuses) a bot-eligible SUPPORT conversation for the visitor. Your frontend then connects the SDK/widget with the returned token and conversation_id. Use this from your backend when you want to provision a widget without exposing your secret key to the browser. For a no-backend embed, use Anonymous Session instead.
Auth: X-Api-Key (pk_…) + X-Api-Secret (sk_…) on production apps. A dashboard JWT is also accepted for non-production (dev/staging) apps. Never expose the secret to the frontend.

Path Parameters

string
required
App ID (UUID).

Request Headers

Request Body

string
required
Your ID for the visitor. Reused across sessions to keep their history.
string
Visitor display name.
string
Visitor email (optional; can also be collected later).
string
Visitor avatar URL.
string
Optional title for the support conversation.

Example Request

Response

string
SDK token for the frontend. Use with the SDK or widget.
string
The support conversation to join.
string
Same as external_user_id.
number
Token lifetime in seconds.

Success (201)

Using the response

Embed the widget

Drop-in support bubble.

Anonymous Session

No-backend embed with a public key.