Conversation lifecycle

POST /api/public/v1/chat/sessions
Origin: https://acme.com
Content-Type: application/json

{
  "publicKey": "pk_live_…",
  "customerId": "u-42",        // optional — your stable user id
  "locale": "en",              // optional — BCP-47
  "variables": {               // optional — seed conversation variables
    "plan": "pro",
    "cart_total": 129.5,
    "page_path": "/checkout"
  }
}

{
  "sessionToken": "eyJ0aWQi…",
  "conversationId": "0193f8a1-…",
  "expiresAt": "2026-05-15T13:00:00Z",
  "widget": { "label": "Demo widget" },
  "intents": [
    { "name": "order_status", "displayLabel": "Order status",
      "description": "Look up the status of an order",
      "examples": ["Where is my order #..."], "required_entities": [] },
    { "name": "returns", "displayLabel": "Returns",
      "description": "Start a return",
      "examples": [], "required_entities": [] }
  ],
  "quickQuestions": [
    { "question": "Where is my order?", "pageType": "general",
      "flowId": "0193aa…", "intentName": "order_status" },
    { "question": "How do I return an item?", "pageType": "product",
      "flowId": "0193bb…", "intentName": null }
  ]
}

POST /api/public/v1/chat/messages
Authorization: Bearer eyJ0aWQi…
Origin: https://acme.com
Content-Type: application/json

{
  "text": "Check the status of my order",
  "intentName": "order_status",
  "context": {                           // optional, free-form
    "page_url": "https://acme.com/orders",
    "referrer": "https://google.com"
  },
  "variables": {                         // optional — same rules as /sessions
    "cart_total": 129.5
  }
}

{
  "reply": {
    "executionId": "01935-aaaa-bbbb-cccc-dddd",
    "conversationId": "0193f8a1-…",
    "status": "waiting_input",
    "blocks": [
      { "id": "b_greeting", "type": "message",
        "payload": { "role": "agent", "text": "What's your order number?", "format": "plain" } },
      { "id": "b_form", "type": "form",
        "payload": {
          "title": "Order lookup",
          "fields": [{ "name": "order_number", "type": "text", "label": "Order #", "required": true }],
          "submit_label": "Check"
        } }
    ],
    "expectedInput": {
      "type": "form_submission",
      "block_id": "b_form",
      "schema": { "type": "object", "required": ["order_number"], "properties": { "order_number": { "type": "string" } } }
    },
    "waitToken": "wt_01935abc",
    "waitExpiresAt": "2026-05-15T13:00:00Z",
    "tokenUsage": {
      "prompt_tokens": 412,
      "completion_tokens": 38,
      "total_tokens": 450,
      "model": "gpt-4o-mini",
      "cost_micros": 124,
      "cost_usd": 0.000124
    }
  }
}

POST /api/public/v1/chat/messages
Authorization: Bearer eyJ0aWQi…
Origin: https://acme.com
Content-Type: application/json

{
  "waitToken": "wt_01935abc",
  "executionId": "01935-aaaa-bbbb-cccc-dddd",
  "values": { "order_number": "12345" }
}

{
  "reply": {
    "executionId": "01935-aaaa-bbbb-cccc-dddd",
    "conversationId": "0193f8a1-…",
    "status": "completed",
    "blocks": [
      { "id": "b_result", "type": "message",
        "payload": { "role": "agent", "text": "Order #12345 ships tomorrow.", "format": "plain" } }
    ],
    "expectedInput": null,
    "waitToken": null,
    "waitExpiresAt": null,
    "tokenUsage": null
  }
}

POST /your-upload-proxy
Content-Type: multipart/form-data; boundary=----xxx

------xxx
Content-Disposition: form-data; name="file"; filename="receipt.pdf"
Content-Type: application/pdf

%PDF-1.4 ... (binary) ...
------xxx--

POST /api/public/v1/chat/messages
Authorization: Bearer eyJ0aWQi…

{
  "waitToken":   "wt_01935abc",
  "executionId": "01935-aaaa-bbbb-cccc-dddd",
  "values": {
    "name":    "Mary",
    "receipt": {
      "file_id": "0193f8a2-7c3e-7c11-bf60-9c1f3f8a2e10",
      "url":     "/api/v1/forms/uploads/0193f8a2-7c3e-7c11-bf60-9c1f3f8a2e10",
      "name":    "receipt.pdf",
      "mime":    "application/pdf",
      "size":    124032
    }
  }
}

GET /api/public/v1/chat/executions/01935-aaaa-bbbb-cccc-dddd
Authorization: Bearer eyJ0aWQi…
Origin: https://acme.com

POST /api/public/v1/chat/events
Authorization: Bearer eyJ0aWQi…
Origin: https://acme.com
Content-Type: application/json

{ "name": "widget_open", "props": { "page": "/pricing" } }

<script>
  const ENDPOINT = 'https://flow.example.com/api/public/v1/chat';
  const KEY = 'pk_live_…';

  class FlowChat {
    constructor() { this.session = null; this.pending = null; }

    async _openSession(customerId, variables) {
      const r = await fetch(`${ENDPOINT}/sessions`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ publicKey: KEY, customerId, variables }),
      });
      if (!r.ok) throw new Error(`/sessions ${r.status}`);
      this.session = await r.json();
      // this.session.intents       — render a menu of buttons
      // this.session.quickQuestions — render tappable chips (skip when intentName is null,
      //                               or render disabled)
      return this.session;
    }

    async _post(body) {
      if (!this.session) await this._openSession();
      const call = () => fetch(`${ENDPOINT}/messages`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.session.sessionToken}`,
        },
        body: JSON.stringify(body),
      });
      let r = await call();
      if (r.status === 401) { this.session = null; await this._openSession(); r = await call(); }
      if (!r.ok) throw new Error(`/messages ${r.status}`);
      const { reply } = await r.json();
      this.pending = reply.status === 'waiting_input'
        ? { waitToken: reply.waitToken, executionId: reply.executionId }
        : null;
      // reply.tokenUsage (or null) — feed an in-conversation usage meter if you show one
      return reply;
    }

    // First message or any free-text turn — pass the chosen intent.
    // `variables` is optional and merged into the conversation.
    sendText(intentName, text, context, variables) {
      return this._post({ intentName, text, context, variables });
    }

    // Tapping a quick-question chip is just a trigger with its intentName:
    askQuickQuestion(q) {
      if (!q.intentName) return Promise.resolve();  // chip is disabled
      return this.sendText(q.intentName, q.question);
    }

    // Form submission while a wait is pending:
    submitValues(values, context, variables) {
      if (!this.pending) throw new Error('No pending form — call sendText() instead');
      return this._post({ ...this.pending, values, context, variables });
    }

    // Poll execution state while the flow is on waiting_time (async work):
    async poll(executionId) {
      const r = await fetch(`${ENDPOINT}/executions/${executionId}`, {
        headers: { 'Authorization': `Bearer ${this.session.sessionToken}` },
      });
      if (!r.ok) throw new Error(`poll ${r.status}`);
      return (await r.json()).reply;
    }

    track(name, props) {
      if (!this.session) return Promise.resolve();
      return fetch(`${ENDPOINT}/events`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.session.sessionToken}`,
        },
        body: JSON.stringify({ name, props }),
        keepalive: true,
      });
    }
  }
</script>