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://breezebuddy.ai/widget/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 the **whole `dist/` directory** into `shopify-apps/breeze-buddy/extensions/assist-widget/assets/` at release time — `assist.js`, `assist.core.js` and `chunks/`. `assist.js` is a small loader that fetches the rest alongside itself, so copying it on its own leaves the widget unable to boot.

If the extension can only hold one file, keep assist.js and point it at the hosted build instead: <script src="…/assist.js" data-core-src="https://breezebuddy.ai/widget/assist.core.js">. The extension then stays a thin pointer and picks up widget updates without being republished.

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