Events & PostMessage

Bi-directional event communication between your host website and the Loops AI widget.

Our widget communicates with the outside world using the window.postMessage API. This allows secure, bi-directional communication with your integration website (Host Website).

Message Flows

Inbound (Host Site → Widget): Send commands or trigger events from buttons inside your site directly to our widget.
Outbound (Widget → Host Site): Listen for user actions taking place inside the chat to update your own website's state.

Cart actions are not postMessage

Add to Cart uses window events that your storefront answers with LoopsAI.cartResult. See Add to Cart.

When a user interacts with product steps inside the chat UI (like closing the chat), the widget sends a message to the parent page (your site).

You can safely listen to these messages using the following JavaScript code:

window.addEventListener("message", (event) => {
  // Event obj contains the message data thrown by Loops AI.
  const data = event.data;

  // We are only listening to specific actions that have the 'action' property.
  if (data && typeof data === "object" && data.action) {
    switch (data.action) {
      case "toggleFavorite":
        console.log("Favorite toggled:", data.productCode, data.isFavorite);
        break;

      case "openUrl":
        // Widget user clicked a redirector link
        window.open(data.url, data.target || "_blank");
        break;

      case "closeChat":
        console.log("Chat was closed.");
        break;
    }
  }
});

TypeScript Payload Guidelines

If your codebase relies on Type Safety, you can use the following Typescript interfaces representing the payload data structures:

interface ToggleFavoriteMessage {
  action: "toggleFavorite";
  productCode: string; // The product code marked as favorite
  isFavorite: boolean; // Was it favorited or un-favorited?
}

interface OpenUrlMessage {
  action: "openUrl";
  url: string;
  target?: "_blank" | "_self";
}

interface CloseChatMessage {
  action: "closeChat";
}

If you want the widget to perform an action instantly when a button on your host website is clicked (For example, a "Suggest Size" button on a product page), you can post a message down into the widget.

While the recommended and easiest method is to use the window.LoopsAI JavaScript API (e.g. LoopsAI.suggestSize() or LoopsAI.openWithSearch(query) for custom search buttons), you may also communicate manually over the iframe.

See Custom Ask AI Search Button.

Direct Iframe Communication

If you wish to send actions manually, find the iframe reference and postMessage it:

const iframe = document.getElementById("loopsmartai-iframe"); // Or whatever ID your integration uses

// 1. Tell the widget to execute a user prompt automatically
iframe.contentWindow.postMessage({
  action: "sendUserMessage",
  message: "I want to receive more info regarding this product."
}, "*");

// 2. Trigger the size suggestion form
iframe.contentWindow.postMessage({
  action: "suggestSize"
}, "*");

Here are some of the popular inbound action payload structures in TypeScript:

// Instantly triggers the size advisor form
interface SuggestSizeMessage {
  action: "suggestSize";
}

// Submits a search query and escalates standard chat
interface SearchEscalationMessage {
  action: "searchEscalation";
  query: string;
  isOnlySearchProducts?: boolean;
}

// Sends a message as the user to continue the conversation flow
interface SendUserMessageMessage {
  action: "sendUserMessage";
  message: string;
}

PostMessage Security

All messages emitted by the widget follow security standards. It's recommended to strictly check the action attribute (if (data.action)) when filtering to listen to widget payload events to avoid conflicts with other 3rd-party embedded providers.

Continue to JavaScript API or other API documentation.

Message Flows

1. Outbound Actions (Widget to Host)

TypeScript Payload Guidelines

2. Inbound Commands (Host to Widget)

Direct Iframe Communication

On this page