Integrate with a website

To broaden the reach of your Business Messages agents, you can add conversation entry points on your websites with the Business Messages widget.

The Business Messages widget only supports mobile devices with Android 5+. Other mobile operating systems and desktop environments aren't supported.

Add a Business Messages widget to a website

To enable conversations from a website, you load the Business Messages JavaScript library, configure widget placement on the page, and specify context values within the widget.

For a list of availability functions, properties, and events, see Business Messages widget. See the Business Messages widget style guide for recommendations in styling and use.

Create a widget

Update the following values to create a Business Messages widget to insert into your website.

Value Description
LAYOUT How the button appears on your website. Can be button, floating, inline, or advanced. To use your own styles, use advanced, copy the stylesheet to your webpage, and modify as required.
AGENT_ID Your Agent ID.
BUTTON_TEXT The text you'd like the button to display. 
    <script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js"></script>
    <button data-bm-widget-layout="LAYOUT" data-bm-widget-agent-id="AGENT_ID">
      <span class="bm-widget-button-text">BUTTON_TEXT</span>
    </button>

Example widget

This widget Web widget preview is generated by the following code:

    <script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js"></script>
    <button data-bm-widget-layout="button" data-bm-widget-agent-id="abcdefghijkl">
      <span class="bm-widget-button-text">Chat with us</span>
    </button>

Customizing the Business Messages widget integration

Load the JavaScript library

To load the Business Messages JavaScript library, copy the following code and paste it immediately within the <head> tag on every page where you want to display a Business Messages widget. You need only one JavaScript library inclusion per page.

<!-- Global Business Messages widget library reference - Business Messages -->
<script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=callback">
</script>

The snippet downloads and loads the JavaScript library, which initializes existing page elements with a data-bm-widget-agent-id attribute. The JavaScript library converts the identified page elements into clickable elements that load the Business Messages conversational surface when tapped.

The optional cb parameter contains the name of a function that is automatically called once the JavaScript library loads.

Configure widget placement

When the Business Messages JavaScript library loads, it scans the website for elements with a data-bm-widget-agent-id attribute and converts these elements into tappable Business Messages widgets. Every element you want to be converted to a widget must include a data-bm-widget-agent-id attribute with a value corresponding to the agent ID for your launched agent.

Example: Widget definitions

<!-- Example div element that converts into a Business Messages widget -->
<div data-bm-widget-agent-id="myagentid">
  Click for Business Messages
</div>

<!-- Example button element that converts into a Business Messages widget -->
<button data-bm-widget-agent-id="myagentid">
  Click for Business Messages
</button>

Pass context values

To configure widget context and pass it to your webhook, include the optional data-bm-widget-context attribute in the HTML element that contains the data-bm-widget-agent-id attribute. Specify a string value for data-bm-widget-context. Messages sent to your webhook include the context value.

data-bm-widget-context can have any value, such as a value relevant to where the widget is shown at runtime on the page. In the following examples, the attribute value of "eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==" is a base64-encoded JSON string of {"product":"dryer","offer-code":"ASDADSA"}.

data-bm-widget-context has a limit of 512 bytes.

Example: Widget definitions with context

<!-- Example div element that converts into a Business Messages widget -->
<div
  data-bm-widget-agent-id="myagentid"
  data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
  Click for Business Messages
</div>

<!-- Example button element that converts into a Business Messages widget -->
<button
  data-bm-widget-agent-id="myagentid"
  data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
  Click for Business Messages
</button>

Sample website

The following sample loads the Business Messages JavaScript library within the <head> tag, which then automatically scans the HTML page and converts "myagentid" into Business Messages widgets.

<html>
  <head>
    <script
      crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js">
    </script>
  </head>
  <body>
    This is a test widget:
    <div
      data-bm-widget-agent-id="myagentid"
      data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
      Click for Business Messages
    </div>
    Click it.
    And this is a widget:
    <button
      data-bm-widget-agent-id="myagentid"
      data-bm-widget-context="VGhpcyBpcyBhIGJ1dHRvbiB0ZXN0Lgo=">
      Click for Business Messages
    </button>
  </body>
</html>

Programmatic widget initialization

For fine-grained control over your setup, you may choose to initialize your widget programmatically. To programmatically initialize an element, call bmwidget.init after the Business Messages JavaScript library loads. This form of initialization doesn't require you to mark elements with the data-bm-widget-agent-id attribute.

<head>
  <!-- Global Business Messages widget library reference - Business Messages -->
  <script
    crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=initWidget">
  </script>

  <script type="text/javascript">
    // Convert HTML element with ID = myCustomButton into a Business Messages widget
    function initWidget() {
      window.bmwidget.init(document.getElementById('myCustomButton'), {
        'agentId': 'myagentid',
        'context': 'eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg=='
      });
    };
  </script>
</head>

Check device support

Use window.bmwidget.supported to verify Business Messages support for a device. The following sample checks for device support prior to initializing the HTML element with ID "myCustomButton" as a Business Messages widget.

<head>
  <!-- Global Business Messages widget library reference - Business Messages -->
  <script
    crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=initWidget">
  </script>

  <script type="text/javascript">
    // Convert HTML element with ID = myCustomButton into a Business Messages widget
    function initWidget() {
      // Check that the user has a supported device
      if (window.bmwidget.supported) {
        window.bmwidget.init(document.getElementById('myCustomButton'), {
          'agentId': 'myagentid',
          'context': 'eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg=='
        });
      }
    };
  </script>
</head>

Widget initialization for Single Page Applications

For Single Page Applications applications, where the data-bm-widget-agent-id attribute is created at runtime, the Business Messages JavaScript library exposes a global object window.bmwidget.

Whenever a new element is added to the page, call window.bmwidget.scan() to initialize the new element as a Business Messages widget.

window.bmwidget.scan();

Call window.bmwidget.scan() on the DOM update callback to ensure the data-bm-widget-agent-id attribute re-initializes when the page changes its state.

Angular Example

The following code initializes window.bmwidget.scan() during the component loading callback in Angular.

import { Component, OnInit} from '@angular/core';

export class AppComponent implements onInit {
  ngOnInit() {
    // Initialize tag on re-render
    window.bmwidget.scan();
  }
}

React Example

The following code initializes the window.bmwidget.scan() function during the rendering of an element in React.

import React, { useState, useEffect } from 'react';

function WrapperComponent() {
  ...
  useEffect(() => {
    // Initialize on re-render
    window.bmwidget.scan();
  });

  return (<div><button data-bm-widget-agent-id="myagentid">Chat with us</button></div>);
}

Next steps

Now that you've integrated a Business Messages widget with your website, you can begin Business Messages conversations from your website and receive widget-specific context values in messages from users.