Widget readiness and analytics events

Listen for readiness and use the built-in consent-controlled GA4 integration.

Listen for message:ready on window, or use window.__msgWidget immediately when it already exists. The event has no conversation or customer payload. It signals API attachment rather than a successful network connection.

Readiness

function configureWidget() {
  const widget = window.__msgWidget;
  if (!widget) return;
  // Call these in response to your own interface controls:
  document.querySelector('#contact-support')?.addEventListener('click', () => {
    widget.open();
  });
}

if (window.__msgWidget) configureWidget();
else window.addEventListener('message:ready', configureWidget, { once: true });

// Other supported panel controls, once ready:
// window.__msgWidget.close();
// window.__msgWidget.toggle();
// window.__msgWidget.open('help');

Configure analytics with consent

The host site must already provide gtag. Configure a valid G- measurement ID and apply the visitor’s actual analytics-consent choice. Consent defaults to off. When the user changes that choice, update setAnalyticsConsent again.

Configure analytics with consent

function applyAnalyticsConsent(granted) {
  const apply = () => {
    const widget = window.__msgWidget;
    widget.configureAnalytics('G-YOURID');
    widget.setAnalyticsConsent(granted);
  };
  if (window.__msgWidget) apply();
  else window.addEventListener('message:ready', apply, { once: true });
}
// Call from your consent manager after the visitor's choice.
// applyAnalyticsConsent(true); // granted
// applyAnalyticsConsent(false); // withdrawn or denied

Built-in GA4 events

The widget forwards message_widget_open, message_chat_started, message_chat_sent and message_chat_resolved when configured and consented. Payloads deliberately omit message text and customer identifiers. The page location is reduced to the site origin rather than a customer-specific URL.

No arbitrary browser event bus

There is no public Message.on or Message.once API for message, typing or assignment events. The authenticated agent and visitor Socket.io protocols are separate interfaces, with separate authorization rules. Do not place agent credentials in a visitor page.