Embed Client Reference

This page is the full surface area of the embed script. Use the Overview for install and orientation; this page is the lookup table.

Script attributes (auto-mount)

These attributes are read off the <script> tag itself. Unknown divinci-* / data-divinci-* / known data-experiment-* attributes produce a console warning, so typos surface quickly during integration.

Attribute	Type	Required	Description
`divinci-release-id`	string (8–64 alphanumeric)	Yes (auto-mount)	The release that drives the chat. Required to auto-mount; if omitted, the script loads but does not create a default chat.
`data-global-name`	string	No	Name of the `window` global the script exposes. Default `"DIVINCI_AI"`.
`css-src`	URL	No	Publicly-reachable stylesheet URL passed into the iframe for theming. Must be a parseable URL.
`debug`	flag	No	When present (or `="true"`), enables verbose console logs in the embed script and forwarded into the iframe.
`divinci-external-user`	flag or JWT string	No	`true` or empty value enables external-login mode (you’ll call `chat.auth.login(jwt)`). Passing a JWT value enables external login and logs in immediately on auto-mount.
`product-recommendations`	flag	No	Enable inline product recommendation UI inside chat.
`metrics`	flag	No	Enable in-chat metrics surfacing.
`help-requests`	flag	No	Enable help-request CTAs.
`notifications`	flag	No	Enable notification surfacing inside the embed.
`context-bubbles`	flag	No	Render RAG context bubbles next to assistant messages.
`message-feedback`	flag	No	Show thumbs-up/down and a feedback dropdown on assistant replies.
`quick-menu`	flag	No	Enable the in-chat quick menu.
`share-chat`	flag	No	Enable share-this-chat affordance.
`data-experiment-id`	string	No	Experiment identifier. When set with a variant, the embed reports the assignment.
`data-experiment-variant`	`"control"` \| `"treatment"`	No	Assigned variant for the experiment. Unknown values are ignored.

Flag values: an attribute being present (with no value, ="true", or any non-"false" value) is treated as enabled. Only ="false" disables it.

`window.DIVINCI_AI` global

When the script loads, it exposes one global keyed by data-global-name (default DIVINCI_AI):

type DivinciAIGlobal = {
  version: string;                                  // package version of the embed
  DivinciChat: typeof DivinciChat;                   // class for manual mounts
  createChat: (opts: CreateDivinciChatOptions) => DivinciChat;
  DEFAULT_CHAT: DivinciChat | null;                  // populated after window.load if auto-mount succeeds
};

DEFAULT_CHAT is null until the load event has fired (or stays null if divinci-release-id was missing).

`createChat(options)` — manual mount

Use this when you want a chat that isn’t auto-mounted, or you want a second chat instance on the page.

const chat = window.DIVINCI_AI.createChat({
  releaseId: "rel_your-release-id",
  toggleable: false,
  contextBubbles: true,
});
document.body.appendChild(chat.iframe);
await chat.waitForReady();

`CreateDivinciChatOptions`

Option	Type	Default	When to use
`releaseId`	`string`	— (required)	Identifies which release configuration drives the chat (model, system prompt, RAG, theme).
`cssSrc`	`string` (URL)	`undefined`	Publicly-reachable stylesheet for white-label theming inside the iframe. Must be a valid URL or the constructor throws.
`debug`	`boolean`	`false`	Verbose logging across the script and iframe bridge.
`externalUser`	`boolean`	`false`	Enables the `auth` sub-API. When `false`, `chat.auth` is `null`.
`productRecommendations`	`boolean`	`false`	Renders inline product cards in assistant responses.
`toggleable`	`boolean`	`false`	When `true`, renders a floating launcher / overlay. When `false`, you mount `chat.iframe` wherever you want and `chat.ui` is `null`.
`metrics`	`boolean`	`false`	Enables metrics surfacing inside the embed.
`helpRequests`	`boolean`	`false`	Enables help-request CTAs.
`notifications`	`boolean`	`false`	Enables notifications inside the embed.
`contextBubbles`	`boolean`	`false`	Renders RAG context bubbles.
`messageFeedback`	`boolean`	`false`	Shows thumbs-up/down + feedback dropdown on assistant replies.
`quickMenu`	`boolean`	`false`	Enables the in-chat quick menu.
`shareChat`	`boolean`	`false`	Enables share-this-chat affordance.
`experimentId`	`string`	`undefined`	Experiment identifier for A/B reporting.
`experimentVariant`	`"control" \| "treatment"`	`undefined`	Assigned variant.

Note on auto-mount defaults: when the script auto-mounts using script-tag attributes, it forces toggleable: true. Manual createChat calls default toggleable to false.

`DivinciChat` instance

class DivinciChat {
  readonly chat: BasicChat;                   // underlying chat controller
  readonly iframe: HTMLIFrameElement;         // mount this where you want chat to appear
  readonly auth: ExternalLogin | null;        // present when externalUser: true
  readonly ui:   ToggleableChat | null;       // present when toggleable: true

  waitForReady(): Promise<void>;
  openSharedChat(shareToken: string): void;   // jumps the iframe to a shared-conversation deep link
  destroy(): void;                            // tear down the chat, auth, and ui
}

Lifecycle

Construct. new DivinciChat({...}) or createChat({...}) synchronously creates chat.iframe. The iframe is not yet attached to the DOM.
Mount. Append chat.iframe to a container, or — for the auto-mounted toggleable: true case — the script handles the mount.
Wait for ready. await chat.waitForReady() resolves once the in-iframe app has booted and the message bridge is connected.
(Optional) log in. If externalUser: true, call chat.auth.login(jwt, opts?) once you have a user JWT.
(Optional) shared chat. chat.openSharedChat(token) redirects the iframe to a 64-hex shared-conversation URL.
Destroy. chat.destroy() tears down the iframe, message bridge, auth, and UI affordances. Call this on SPA route changes when the chat should go away.

Errors thrown by the constructor

releaseId is required — empty releaseId.
Invalid cssSrc — cssSrc is not a parseable URL.

`chat.auth` — `ExternalLogin`

Present only when externalUser: true. Manage your end-user identity in the embed.

interface ExternalLogin {
  readonly user: User | null;
  readonly isLoggedIn: boolean;
  readonly tierConfig: TierConfig | null;
  readonly onUserChange: EventListener<[User | null]>;

  login(jwt: string, options?: LoginOptions): Promise<LoginResult>;
  logout(): Promise<void>;
  getCurrentUser(): User | null;
}

type LoginOptions = {
  tier?: "free" | "basic" | "premium" | "enterprise" | "unlimited";
  pricingTier?: "non_member" | "gold_member" | "platinum_member" | "diamond_member";
  metadata?: Record<string, unknown>;
};

type LoginResult = {
  user: { id: string };
  tierConfig: TierConfig;  // tier, limits, usage, remaining, pricingTier
};

The tier you pass in LoginOptions is a request — the server validates and may return a different tier in tierConfig. pricingTier is a BigCommerce-only hint for which price band to display.

Example: log in once the host page knows the user:

const chat = window.DIVINCI_AI.DEFAULT_CHAT;
await chat.waitForReady();

const result = await chat.auth.login(myJwt, { tier: "premium" });
console.log("logged in as", result.user.id, "tier:", result.tierConfig.tier);

// Subscribe — calling the event returns an unsubscribe function
const unsubscribe = chat.auth.onUserChange((user) => {
  console.log("user changed:", user);
});
// later: unsubscribe();

`chat.ui` — `ToggleableChat`

Present only when toggleable: true. Controls the floating launcher / overlay.

interface ToggleableChat {
  readonly isOpen: boolean;
  toggleChat(): void;
  openChat(): void;
  closeChat(): void;
  onToggle: EventListener<[boolean]>;
}

Example: programmatically open chat from a “Need help?” button on your page:

document.querySelector("#help-button").addEventListener("click", () => {
  window.DIVINCI_AI.DEFAULT_CHAT?.ui?.openChat();
});

window.DIVINCI_AI.DEFAULT_CHAT?.ui?.onToggle((isOpen) => {
  console.log("chat is now", isOpen ? "open" : "closed");
});

`chat.chat` — `BasicChat`

The underlying chat controller, primarily exposed for state observation.

interface BasicChat {
  readonly state: "not-ready" | "getting-ready" | "error" | "ready" | "destroyed";
  readonly onStateChange: EventListener<["not-ready" | "getting-ready" | "error" | "ready" | "destroyed"]>;
  waitForReady(): Promise<void>;
}

chat.waitForReady() on the top-level DivinciChat delegates to this.

Shared-chat deep links

chat.openSharedChat(token) navigates the iframe to a read-only shared-conversation URL. The token is validated client-side as a 64-character lowercase hex string; an invalid token throws Invalid share token — must be a 64-character hex string. The shared chat becomes a fork the moment the user sends a message.

const chat = window.DIVINCI_AI.createChat({ releaseId: "rel_..." });
document.body.appendChild(chat.iframe);
await chat.waitForReady();
chat.openSharedChat("abc123...token...");  // 64 hex chars

CSS customization

Theming happens inside the iframe — your host-page CSS cannot reach it. Two surface areas:

cssSrc attribute / option: points to a stylesheet hosted at a publicly-reachable URL. The embed loads it inside the iframe and applies its rules. Use this for white-label color, typography, spacing, and component overrides.
CSS variables exposed by the embed app: the embed exposes themeable CSS variables that cssSrc stylesheets can override. The current set is documented in your release’s white-label configuration in the Divinci dashboard.

The launcher button (when toggleable: true) and floating overlay are styled by the embed app itself; theme them via cssSrc.

Event hooks summary

Hook	When it fires
`chat.chat.onStateChange`	Every transition between `not-ready / getting-ready / ready / error / destroyed`.
`chat.auth.onUserChange`	After successful login, logout, or external token refresh.
`chat.ui.onToggle`	Every time the toggleable overlay opens or closes.

Each hook is an EventListener<[Args]> from @divinci-ai/embed-shared. It is a callable: invoking it with a handler subscribes and returns an unsubscribe function. Equivalent .on(handler) / .off(handler) methods are also available.

// Subscribe (callable form) — returns an unsubscribe function
const unsubscribe = chat.ui.onToggle((isOpen) => { /* ... */ });
unsubscribe();

// Or use the explicit methods
const handler = (isOpen) => { /* ... */ };
chat.ui.onToggle.on(handler);
chat.ui.onToggle.off(handler);

Embed Client Reference

Script attributes (auto-mount)

window.DIVINCI_AI global

createChat(options) — manual mount

CreateDivinciChatOptions

DivinciChat instance