On-Page Triggers

Always-accessible entry points that live on the page itself: the floating trigger and the homepage banner widget.

Floating Trigger

Always accessible, never intrusive. A floating trigger in the corner of the viewport is reachable from any page — homepage, PDP, PLP, campaign — and opens the assistant only when the shopper asks for it, so it never interrupts the journey.

So the sample below does two things the SDK will not do for you: it passes height: '100%', and it toggles the container alongside show().

const widget = new SophiWidget();

// position: fixed; inset: 0; display: none — a full-viewport overlay of your own.
// It must start hidden: a transparent fixed container would otherwise swallow
// every click on the storefront underneath it.
const container = document.querySelector('#sophi-widget-container');

await widget.init({
  apiKey: 'YOUR_SOPHI_API_KEY',
  container,
  // The container supplies a definite height; '100%' makes the iframe fill it.
  width: '100%',
  height: '100%',
});

// init() resolves once the iframe is mounted, so enable the trigger here
trigger.disabled = false;

trigger.addEventListener('click', () => {
  container.style.display = 'block';
  widget.show();
});

closeButton.addEventListener('click', () => {
  widget.hide();
  container.style.display = 'none';
});

SDK reference

• await widget.init(config) — mounts the iframe into container at width/height (defaults 100% and 600px). Pass height: '100%' for a full-viewport placement.
• widget.show() / widget.hide() — toggle the iframe's display. Your container's visibility is yours to manage.
• widget.isReady() — true once init() has resolved and the iframe exists. Use it (or simply the line after await init(...)) to gate the trigger.

Homepage Widget

Open with an invitation, not a button. A widget card in the homepage banner slot puts suggested prompts in front of shoppers the moment they arrive — delivery, returns, exchanges, gift-finding — so the first interaction is a question they already had rather than a chat icon they have to notice. Unlike the floating trigger, it occupies the page's primary slot and sets the tone for the visit.

Each chip is a prompt. Send its text and let the conversation start already in progress:

// Banner chips hand their prompt straight to the widget
bannerChips.addEventListener('click', (event) => {
  const chip = event.target.closest('[data-sophi-prompt]');
  if (!chip || !widget.isReady()) return;

  widget.show();
  // sendTextMessage posts to the iframe and returns void — there is nothing to await
  widget.sendTextMessage(chip.dataset.sophiPrompt);
});

SDK reference

• widget.sendTextMessage(query) — each banner chip hands its prompt straight to the chat.
• widget.sendToggleHistory() — toggles past conversations, for a returning-shopper entry point.