Widget iframe messaging (postMessage)

The internal postMessage protocol between the embed shell and Hubbo-hosted iframes, and what is safe to rely on.

Parts of the Hubbo widget, such as the notification widget, are rendered in an iframe that loads from app.hubbo.io. The embed shell on your page and the iframe coordinate with window.postMessage. This article documents that traffic so you can understand it in DevTools and avoid breaking it.

Internal protocol, not an SDK

Do not drive the widget through these postMessages in production — they are an implementation detail and may change without notice. The supported page API is window.hubbo.identify() / reset() / getVisitor() for auth targeting and setLang() / getLang() for translations (Identify visitors, Set visitor language). Use the messages below for debugging only.

Message shape

type HubboMessage = {
  target: 'hubbo:notifications' | 'hubbo:nps';
  action: string;
  params?: Record<string, unknown>;
};

Every message carries a target that names the module and an action. Receivers ignore messages whose target is not theirs.

Notifications (target hubbo:notifications)

Action	Direction	Meaning
request-bootstrap	iframe to embed	The iframe asks the embed shell for its initial data.
bootstrap	embed to iframe	The embed shell sends the account (and, outside previews, the notification list) so the widget renders faster. The iframe still loads its own data over GraphQL.
page-loaded	iframe to embed	The widget finished loading, the shell can hide its loader.
show-notification	to embed	Replaces the notification list shown by the shell.
show-widget / hide-widget	to embed	Opens or closes the widget.
request-save-notification	embed to parent	Used in admin previews: the user clicked a link and the editor asks to save first. Params include the channel.

NPS (target hubbo:nps)

Action	Meaning
toggle	Opens or closes the NPS widget.

DOM events

Inside the shell, tooltips listen for a hubbo:close-all-tooltips window event, which is dispatched when the notification widget opens. That dismisses the tooltip for subsequent visits (same as closing it), unless the notification has the preserve flag.

If you listen to messages on your page

Messages are posted with a wildcard target origin so the embed shell and iframe can talk across hosts; any script on the page can observe them. If you add your own message listener, check event.origin (typically https://app.hubbo.io for the iframe) and event.data.target, and never act on data from an unexpected origin. Do not treat postMessage payloads as authenticated instructions.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.hubbo.io') return;
  if (event.data?.target !== 'hubbo:notifications') return;

  // Inspect only. Do not rely on these messages for logic.
  console.debug('Hubbo message', event.data.action);
});

What you can control

To change how widgets look and when they appear, use the admin app: appearance, categories, URL rules, device toggles, delays and throttling. See the Help Center.