Concept

Overview

What Buddy Assist is, how the widget-public architecture works, and when to use it.

Buddy Assist is Breeze Buddy’s storefront chat widget — a self-contained <breeze-buddy-assist> custom element that merchants embed on their website or Shopify storefront to offer an AI-powered chat (and optionally voice) assistant to shoppers.

Unlike the authenticated voice API (which requires a server-side JWT), Buddy Assist uses a widget-public auth model: a short-lived widget_token minted at session creation gates all follow-up calls, and the only credential the embed needs is an opaque public_widget_key generated from the admin API.

Request lifecycle

Storefront loads the embed Shadow DOM mounts, launcher FAB appears

Create session Origin verified, 24 h token returned

Chat turn SSE stream, LLM returns text + UI ops

Continue in Chat

Switch to Voice

Page reload — session resumes Token read from localStorage, full history restored

Key design choices


Auth	No JWT from the storefront. `public_widget_key` + Origin allowlist gate session create; `widget_token` (24 h) covers all follow-up calls.
Shadow DOM	Host-page CSS cannot bleed in; widget CSS cannot bleed out.
One thread	Chat and voice share one `chat_session`. Voice is a transient attachment — its transcript drains back into chat history when it ends.
Rate limits	Sessions, messages, concurrent sessions, and voice connects are all capped per IP, per merchant, in `widget_config`.
Session resume	`session_id` + `widget_token` stored in `localStorage`. Page reload within the TTL restores the full conversation.
No recording	Voice recording is disabled for widget sessions by design.

When to use Buddy Assist vs the raw API

Use case	Reach for
Storefront chat / Shopify	Buddy Assist widget
Custom chat UI (React / Vue)	`createBuddyChatStore` from the Client SDK
Outbound voice calls / IVR	Leads + Connect API — Build with Telephony
In-browser voice, custom UI	`BuddyClient` / `joinRoom` from the Client SDK

Next steps

Quickstart

Embed the widget in 5 minutes

Embed reference

All attributes, events, and methods

Voice mode

Chat ↔ voice channel lifecycle

Widget config API

Admin API for per-merchant configs

Shopify end-to-end setup

widget_config → tunnel → theme snippet → verify

Was this helpful?

Edit on GitHub