Build a custom chat launcher

Use the site embed identifier

Copy your current snippet from https://app.message.com/settings/chats/installation. Replace YOUR_EMBED_ID with the data-site-id value from that snippet. It is the site’s public embed identifier, not the workspace database ID or a secret API key.

Install once in the persistent page or application shell. The bundle renders its own launcher and panel inside Shadow DOM.

<script async src="https://app.message.com/widget.js"
  data-site-id="YOUR_EMBED_ID"></script>

Add an accessible button

Render a normal button with id="contact-support" and a clear label such as Chat with us. Keep it disabled until the widget is ready if your page loads slowly. The standard widget launcher remains available.

Wire the click after readiness

Check the API before subscribing to the readiness event. Do not open automatically on every render.

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

Use the supported controls

There is no public unread-count subscription or data-no-launcher attribute. close(), toggle() and open(view) control the panel, not an authenticated customer session.

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.