Business Messages widget

  • The Business Messages widget JavaScript library initializes widgets and tracks engagement.

  • The init function dynamically initializes a single HTML element as a widget.

  • The scan function automatically finds and converts HTML elements with a specific attribute into widgets.

  • The supported property indicates if Business Messages is supported on the user's device.

  • Events like bm-widget-bind-success, bm-widget-bind-fail, and bm-widget-intent-trigger signal different stages and actions related to widget interaction.

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