Methods

Lifecycle and UI

await widget.init(config)

Initializes the widget and mounts an iframe into the given container.

await widget.destroy()

Destroys the widget, removes listeners and iframe, and resets internal state.

await widget.destroy();

widget.isReady()

Returns whether the widget is initialized and ready.

if (widget.isReady()) {
  console.log("Widget active");
}

widget.show() / widget.hide()

Toggles iframe visibility.

widget.hide();
widget.show();

await widget.setStorageConsent(granted)

Updates cookie/storage consent at runtime without losing the open chat. Use it together with storageConsent: false at init to run the widget in Cookie Consent Management.

When granting consent:

• The current in-memory session is persisted to cookies.
• For a logged-in user (a userId was provided at init), the anonymous guest session is merged into that user account.
• The chat iframe promotes its in-memory store to localStorage, so the conversation survives the next reload — no re-init required.

// Visitor accepted cookies in your consent banner
await widget.setStorageConsent(true);

// Visitor withdrew consent
await widget.setStorageConsent(false);

Data and communication

widget.updateUserCart(cart)

Pushes latest cart state to widget runtime.

Minimal sequence:

await widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container" });

widget.on("add_to_cart", async (data) => {
  await addToCartInYourApp(data.products);
  widget.updateUserCart({ cartId: cartId, items: cartItems });
});

widget.on("send_to_checkout", () => {
  window.location.href = "/checkout";
});

widget.updateUserCart({
  cartId: "cart-001",
  items: [
    { productId: "p1", variantId: "v1", quantity: 1 },
    { productId: "p2", variantId: "v2", quantity: 2 },
  ],
});

widget.sendToggleHistory()

Toggles the chat history panel inside the widget. No-op with a console.warn if the widget is not initialized.

widget.sendToggleHistory();

Chat messages

These methods let the host application send typed chat messages directly into the Sophi widget. All three are no-ops — they log a console.warn and return immediately — when the widget iframe has not yet initialised.

widget.sendTextMessage(query)

Sends a plain chat message to the widget with no product or outfit context.

Posts the following message to the iframe:

{ type: "send_text_message", data: { query } }

Example

widget.sendTextMessage("What should I wear today?");

widget.sendProductReply(product, opts?)

Sends a chat message scoped to a specific product card. productId is derived automatically from product.id — do not pass it separately.

Supply opts.query and opts.isOutfit when the query intents to outfit context.

Posts the following message to the iframe:

{
  type: "send_product_reply",
  data: {
    query,
    externalProductId
    isOutfit?,                // from opts.isOutfit, if provided
  }
}

Type definitions

interface ProductReplyOptions {
  query?: string; // Optional follow-up question or message to send alongside the product reply
  isOutfit?: boolean; // Set to true when the query involves outfit context
}

Examples

// Basic external Product Id query
widget.sendProductReply(externalProductId, {
  query: "Does this come in blue?"
});

// Product that belongs to an outfit recommendation
widget.sendProductReply(externalProductId, {
  query: "Tell me about this jacket"
  isOutfit: true,
});
// Open chat with given external product
widget.sendProductReply(externalProductId, {
  isOutfit: true,
});

UI controls

These methods are no-ops — they log a console.warn and return immediately — when the widget iframe has not yet initialised.

widget.openProductById(externalProductId, reason?)

Instructs the widget to fetch the product and open the product detail panel, identical to the user clicking a product card in the chat results. The iframe resolves the full product data itself from the given ID.

Posts the following message to the iframe:

{ type: "open_product_by_id", data: { externalProductId, reason? } }

Type definition

interface OpenProductByIdPayload {
  externalProductId: number;
  reason?: string;
}

Examples

// Open the product detail panel for product ID 123
widget.openProductById(123);

// Open with a recommendation reason
widget.openProductById(123, "Matches your style preferences");

widget.triggerProductReply(product) ⚠️ Deprecated

Sets a product as the active reply context in the chat input bar, identical to the user clicking Ask a Question on a product card. The reply popover appears above the input with the product pre-filled. The user then types their question and sends it — the outgoing message will be delivered as a product-context reply.

Posts the following message to the iframe:

{ type: "trigger_product_reply", data: { product } }

Type definition

interface TriggerProductReplyPayload {
  product: ProductSummary;
}

See sendProductReply for the full ProductSummary interface definition.

Example

// Pre-fill the chat input reply bar with a product context
widget.triggerProductReply(product);

Advanced methods quick list

These methods are typically used in advanced UI flows:

• sendToggleHistory
• sendProductReply
• triggerProductReply

Events API

widget.on(event, handler)

Registers an event listener.

widget.off(event, handler)

Removes a previously registered listener.