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();

Data and communication

widget.updateUserCart(cart)

Pushes latest cart state to widget runtime.

widget.updateUserCart({
  cardId: "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.

Parameter	Type	Required	Description
query	string	Yes	The user's text query.

Posts the following message to the iframe:

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

Example

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

---

widget.sendProductReply(query, 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.outfitId and opts.isOutfit when the product belongs to an outfit recommendation or the query involves outfit context.

Parameter	Type	Required	Description
query	string	Yes	The user's text query.
product	ProductSummary	Yes	The product the user is asking about.
opts	ProductReplyOptions	No	Optional outfit context.

Posts the following message to the iframe:

{
  type: "send_product_reply",
  data: {
    query,
    productId: product.id,   // derived automatically
    product,
    outfitId?,                // from opts.outfitId, if provided
    isOutfit?,                // from opts.isOutfit, if provided
  }
}

Type definitions

interface ProductImage {
  url: string;
  isPrimary: boolean;
  sortOrder: number;
  altText: string | null;
}

interface ProductOffer {
  listPrice: number;
  salePrice: number;
  discountRate: number | null;
  currency: string;
}

interface ProductSummary {
  id: number;
  externalId: string;
  displayName: string;
  shortDescription: string;
  images: ProductImage[];
  rating: number;
  favoriteCount: number;
  bestOffer: ProductOffer;
  brandName: string;
  isAvailable: boolean;
  totalStock: number;
}

interface ProductReplyOptions {
  outfitId?: number;   // Numeric outfit ID — set when the product belongs to an outfit
  isOutfit?: boolean;  // Set to true when the query involves outfit context
}

Examples

// Basic product query
widget.sendProductReply("Does this come in blue?", product);

// Product that belongs to an outfit recommendation
widget.sendProductReply("Tell me about this jacket", product, {
  outfitId: 7,
  isOutfit: true,
});

---

widget.sendOutfitReply(query, outfit)

Sends a chat message scoped to a full outfit recommendation. outfitId is derived automatically from outfit.recommendationId — do not pass it separately.

Parameter	Type	Required	Description
query	string	Yes	The user's text query.
outfit	OutfitResponse	Yes	The outfit recommendation the user is asking about.

Posts the following message to the iframe:

{
  type: "send_outfit_reply",
  data: {
    query,
    outfitId: outfit.recommendationId,   // derived automatically
    outfit,
  }
}

Type definitions

interface OutfitResponse {
  recommendationId: number;
  outfitName: string;
  items: OutfitItem[];
}

interface OutfitItem {
  productId: number;
  reason: string;
  recommendationId: number;
  detail: ProductSummary;
}

Example

widget.sendOutfitReply("Can you style this differently?", outfit);

---

Note

All three methods (sendTextMessage, sendProductReply, sendOutfitReply) silently no-op and emit a console.warn when called before the widget iframe is ready. Call them only after the ready event has fired or widget.isReady() returns true.

UI controls

These methods control UI state — not the chat assistant

openProductById and triggerProductReply drive the widget's visual state directly via postMessage. They do not send a query to the chat assistant, trigger a chat response, or alter conversation history. Use the Chat messages methods when you want the chat assistant to respond.

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

widget.openProductById(productId, 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.

Parameter	Type	Required	Description
productId	number	Yes	Internal numeric product ID to open.
reason	string	No	Recommendation reason text shown alongside the product.

Posts the following message to the iframe:

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

Type definition

interface OpenProductByIdPayload {
  productId: 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)

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.

Parameter	Type	Required	Description
product	ProductSummary	Yes	Full product summary object to set as the reply context.

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);

---

Note

Both openProductById and triggerProductReply silently no-op and emit a console.warn when called before the widget iframe is ready. Call them only after the ready event has fired or widget.isReady() returns true.

Events API

widget.on(event, handler)

Registers an event listener.

widget.off(event, handler)

Removes a previously registered listener.