Skip to main content
POST
/
api
/
public
/
v1
/
chat
/
sessions
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({publicKey: 'pk_live_1a2b3c4d5e6f7890abcd1234ef567890'})
};

fetch('{protocol}://{host}/api/public/v1/chat/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "sessionToken": "<string>",
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expiresAt": "2023-11-07T05:31:56Z",
  "widget": {
    "label": "<string>"
  },
  "intents": [
    {
      "name": "<string>",
      "displayLabel": "<string>",
      "subtitle": "<string>",
      "description": "<string>",
      "examples": [
        "<string>"
      ],
      "required_entities": [
        "<string>"
      ],
      "icon": {
        "kind": "<string>",
        "value": "<string>"
      },
      "accentColor": "<string>",
      "styleVariant": "solid",
      "isPinned": true,
      "priority": 123
    }
  ],
  "quickQuestions": [
    {
      "question": "<string>",
      "pageType": "general",
      "flowId": "<string>",
      "intentName": "<string>"
    }
  ]
}

Body

application/json
​
publicKey
string
required
Pattern: ^pk_live_[a-f0-9]{32}$
Example:

"pk_live_1a2b3c4d5e6f7890abcd1234ef567890"

​
customerId
string

Your stable user identifier. Used for cross-session history joins and analytics.

Maximum string length: 100
​
locale
string

BCP-47 locale forwarded to the flow as conversation context.

Maximum string length: 16
​
variables
object

Optional conversation variables merged into the conversation row and surfaced to the flow as untrusted input. Constraints (rejected with a 422 validation_failed on the chat surface, 422 invalid_input on the Engine API):

  • at most 50 keys;
  • at most 4096 bytes total when JSON-encoded;
  • keys are snake_case matching ^[a-z][a-z0-9_]{0,63}$;
  • values are scalar, null, or arrays nested at most 4 levels deep (plain objects/maps as values are rejected).
Example:
{
  "cart_total": 129,
  "page_path": "/pricing",
  "tags": ["returning", "vip"]
}

Response

Session opened

​
sessionToken
string
required

HMAC-signed bearer token. Pass as Authorization: Bearer <token> on subsequent calls.

​
conversationId
string<uuid>
required
​
expiresAt
string<date-time>
required
​
widget
object
required
​
intents
object[]

Intents this widget may trigger, intersected with the tenant's currently-published flows. Empty when the widget key has an explicit allow-list that doesn't intersect any published intent — the chat is effectively unavailable until either the key's list is widened or matching flows are published.

​
quickQuestions
object[]

Tenant-configured quick-question prompts. Each prompt carries its display text, the page context it should surface on, and — when its assigned flow is published and this widget key is permitted to trigger it — the intentName the widget posts to start it. A prompt whose flow is unset, unpublished, or not permitted comes back with a null intentName so the client can still render it (disabled). Page filtering is left to the client.