Updates: Check the release notes for new features and product updates.

Business Messages widget

The Business Messages widget JavaScript library programmatically initializes and enables engagement tracking for Business Messages widgets.

Functions and properties

Functions and properties provide fine-grained control over element initialization.

Init

Dynamically initializes an HTML element to be used as a Business Messages widget. The function returns a promise that resolves when initialization is complete.

window.bmwidget.init(HTMLElement, {agentId, context}):Promise
  • HTMLElement is the element to initialize as a widget.
  • {agentId, context} are the values for the data-bm-widget-agent-id and data-bm-widget-context HTML attributes.

Scan

Scans the document for any HTML elements that contain a data-bm-widget-agent-id attribute and converts those elements into Business Messages widgets. window.bmwidget.scan() is automatically called on page load and during script initialization.

window.bmwidget.scan():void

Supported

Read-only boolean flag that is true if the user's device supports Business Messages.

window.bmwidget.supported:boolean

Events

The library triggers events on HTML elements it initializes as Business Messages widgets.

Bind success

The bm-widget-bind-success event triggers when an HTML element is successfully bound as a Business Messages widget and is ready for use.

domNode.addEventListener('bm-widget-bind-success', (event) => {
  console.log(event.data);
});

Bind fail

The bm-widget-bind-fail event triggers when an attempt to bind to an HTML element fails. This may happen because of a failure to validate the URL or because of a general failure to get the HTML element. Failure to validate happens if the url has not been registered as Business Messages widget entry point or the user's device is unsupported. The event.data property details the cause of failure.

domNode.addEventListener('bm-widget-bind-fail', (event) => {
  console.log(event.data);
});

Intent trigger

The bm-widget-intent-trigger event triggers when a user taps an initialized Business Messages widget entry point. This event signals a tap but doesn't indicate whether the Business Messages conversational surface successfully initialized.

domNode.addEventListener('bm-widget-intent-trigger', (event) => {
  console.log(event.data);
});