Quickstart

Quickstart

Embed the Buddy Assist chat widget on any website or Shopify storefront in under 5 minutes.

Prerequisites

  • A Clairvoyance account with admin or reseller access.
  • A template already created for your merchant — see Templates.
  • The Clairvoyance API base URL (e.g. https://clairvoyance.breezelabs.app).

Step 1 — create a widget config

A widget_config row ties a merchant’s public_widget_key to a template and defines the allowed origins that can load the widget.

POST /agent/voice/breeze-buddy/widget-config 
{
  "reseller_id": "acme-reseller",
  "merchant_id": "acme-store",
  "template_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "allowed_origins": [
    "https://acme-store.myshopify.com",
    "https://www.acme.com"
  ],
  "max_sessions_per_ip_hour": 60,
  "max_messages_per_ip_hour": 600,
  "max_concurrent_per_ip": 4,
  "max_voice_sessions_per_ip_hour": 10,
  "active": true
}

The response contains public_widget_key — the opaque token your embed tag uses.

{
  "id": "wc_01J…",
  "public_widget_key": "BPlS8aL3Xk7tRvNqZ…",
  "reseller_id": "acme-reseller",
  "merchant_id": "acme-store",
  "template_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "allowed_origins": ["https://acme-store.myshopify.com", "https://www.acme.com"],
  "active": true
}

allowed_origins must not be empty

An empty `allowed_origins` list makes the widget reject every request. Populate it with your storefront's exact origin (scheme + host, no trailing slash) before going live.

Step 2 — add the embed snippet

Drop two lines into your storefront HTML — the custom element and the script loader.

<!-- Place near </body> on every storefront page -->
<breeze-buddy-assist
  tenant="BPlS8aL3Xk7tRvNqZ…"
  api-base="https://clairvoyance.breezelabs.app"
></breeze-buddy-assist>
<script src="https://widget.breezebuddy.com/assist.js" async></script>

tenant is the public_widget_key from Step 1. api-base points to your Clairvoyance deployment.

Shopify Theme App Extension

For Shopify storefronts, copy `dist/assist.js` into `shopify-apps/breeze-buddy/extensions/assist-widget/assets/assist.js` at release time. The Theme App Extension injects the tag automatically; you only set `tenant` and `api-base` in the extension settings.

Step 3 — optional: pass customer context

If your storefront has a logged-in customer, pass their identity as template_vars so the AI can personalise the conversation. Do this by setting the customer-token attribute to a short-lived token your backend mints:

<breeze-buddy-assist
  tenant="BPlS8aL3Xk7tRvNqZ…"
  api-base="https://clairvoyance.breezelabs.app"
  customer-token="eyJ…"
></breeze-buddy-assist>

See Embed reference — customer-token for the token shape.

Step 4 — verify it works

Open the storefront page. You should see a launcher FAB (floating action button) in the bottom-right corner. Click it — a chat panel opens and the agent sends the template’s greeting message.

Open the browser console and look for:

breeze-buddy-assist:ready

That custom event fires as soon as the element mounts, before any session is created.

Quick theming

Override brand colors without touching the Shadow DOM internals:

<breeze-buddy-assist
  tenant="…"
  api-base="…"
  primary-color="#6c47ff"
  header-title="ACME Assistant"
  header-logo-url="https://cdn.acme.com/logo-44.png"
  launcher-label="Chat with us"
></breeze-buddy-assist>

Full theming reference → Embed reference — theming.

Was this helpful?
Edit on GitHub