The Widget adds a chat bubble to your website. Customers click it to open a conversation with your AI Agent. Texts, design, availability and display conditions come from your Configuration. You can override some of them in code and control the Widget with a JavaScript API.

Before you start

1. Save your Conversation SDK configuration.
2. In Automate → Channels, turn on Widget on the Conversation SDK card.

If the Widget is turned off on the card, the snippet loads nothing.

Install the Widget

JavaScript snippet

1. On the Conversation SDK card, click Snippet next to Widget.
2. Copy the code and paste it before the closing </body> tag on every page where the Widget should appear.

The snippet looks like this. Always copy yours from the card, because the script address depends on your account:

<script type="text/javascript">
  (function(cb) {
    var js = document.createElement("script");
    if (js.readyState) {js.onreadystatechange = function() {if (js.readyState === "loaded" || js.readyState === "complete") {js.onreadystatechange = null; cb();}};
    } else {js.onload = function(){cb();};}
    js.type = "module";
    js.defer = true;
    js.src = "https://<your-chat-host>/zowie-widget-entry.js";
    document.body.appendChild(js);
  })(function() {
    ZowieWidget.init("<your-instance-id>", {});
  });
</script>

Google Tag Manager

1. In Google Tag Manager, create a new tag of type Custom HTML.
2. Paste the snippet from the card.
3. Set the trigger to All Pages, or to the pages where the Widget should appear.
4. Save the tag and publish the container.

Customize the Widget in code

The second argument of ZowieWidget.init is a configuration object. Values you pass there take priority over the values from your configuration in Zowie.

ZowieWidget.init("<your-instance-id>", {
  primaryColor: "#2563EB",
  theme: "system",
  metadata: {
    firstName: "Ada",
    email: "[email protected]",
  },
  onStartChat: (conversationId) => {
    console.log("Conversation started", conversationId);
  },
});

Call init once per page. Later calls are ignored.

Init options

Behavior

Customer data and authentication

Branding

Hello (voice)

Callbacks

Pass these functions in the configuration object to react to what happens in the Widget.

Options, callbacks and methods for online stores are described in E-commerce.

Control the Widget

After the Widget has loaded, you can control it through the global ZowieWidget object. Calls made before the Widget has loaded are ignored, so call these methods from onLoaded or later. The exception is on(), which you can call at any time.

ZowieWidget.init("<your-instance-id>", {
  onLoaded: () => {
    document.querySelector("#help-button").addEventListener("click", () => {
      ZowieWidget.startChat();
    });
  },
});

Types

PositionOffsets

All values are in pixels.

ShowCTAConfig

Both desktop and mobile are optional. Pass only the one you need.