Widget JavaScript controls

Wait for the public API

The bundle exposes window.__msgWidget and dispatches message:ready on window when the public API is attached. Check for an existing API first so code also works after that event has fired. Ready means the controls are attached; it does not guarantee the server is connected.

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

Supported panel methods

open() opens the current conversation when one exists, otherwise Home. close() closes the panel. toggle() behaves like clicking the launcher. open(view) accepts home, pre-chat, conversation, messages, help, post-chat and booking. Opening a view does not create a conversation or bypass its prerequisites.

Analytics controls

configureAnalytics(measurementId) configures the built-in GA4 event forwarding. setAnalyticsConsent(boolean) enables or disables that forwarding. These methods use the host site’s existing gtag installation; they do not load Google’s tag or create a consent interface.

Methods that are not available

The widget does not expose the old Message or MessageCom browser APIs. There is no public sendMessage, identify, signout, update, track, setTheme or arbitrary event-subscription method. Configure appearance and pre-chat fields in the dashboard. There is no public destroy method; mount the widget once.

Verify the published installation

Test the published page in a separate browser session. Confirm widget.js loads, the launcher opens, a visitor message reaches Inbox and an agent reply returns. Test with your site’s actual content security policy, consent controls and mobile layout.

The script connects to its own origin by default. With the standard snippet, allow the relevant script and HTTPS/WSS requests to app.message.com. Check image, media and injected-style requirements separately. Do not put an agent JWT or integration secret in the page.