Skip to main content

Custom app shopping assistant

Bootstrap from your backend​

Call POST /api/v1/assistant/bootstrap with the tenant API key. Send the client surface and optional locale/customer/conversation context. The response contains branding, assistant capabilities, a short-lived bootstrap token, and Broker endpoints.

Run the client session​

  1. POST /public/v1/chat/session to create/resume a Broker-owned session.
  2. POST /public/v1/chat/messages with a unique idempotency key.
  3. Read GET /public/v1/chat/stream using after_cursor, or connect to the SSE endpoint.
  4. Persist the last cursor locally and reconnect from it.

The message acceptance response means the message was durably admitted; the answer arrives through the stream. Render transcript messages, deltas, statuses, and artifacts in cursor order. Product cards use managed media URLs and artifact-carried product destinations.

Control and failure behavior​

Pre-assignment sessions may report control_mode: unassigned. Respect routing_status, ai_routing_eligible, and handoff state. Render explicit assistant failure events instead of waiting forever. Do not fabricate a reply when the stream reports a governed failure.

Security​

Long-lived tenant credentials stay on your backend. The client receives only short-lived bootstrap/session material. Validate the origin/surface you requested and never reuse material across tenants.