Implementing the Customer AI Assistant on your website

This article explains how to put the Customer AI Assistant chat on your website once the assistant is configured in AI Hub. You can do it in two ways:

• Without changing your website's code - with a Dynamic Content campaign. Synerise injects the chat into the page through the tracking code. This is the fastest way to start and the easiest to switch off.
• In your website's code - your developers add the chat where they want it, with full control over placement and behavior. This is the recommended way for a permanent implementation.

Both ways use the same chat component with the same options, so you can start with a campaign and move the code into your website later.

Prerequisites

1. Implement the tracking code on the pages where the chat should appear. The chat identifies the customer through the Synerise Web SDK and cannot start a conversation without it.
2. Create and save an assistant in AI Hub > AI Assistant, as described in Configuring Customer AI Assistant in the Synerise platform, and test it in the Preview tab.
3. Decide where the chat window appears and what opens it. The chat is closed after initialization; your page provides the launcher (a button or icon) that opens it.
4. Optional: add Open Graph tags to your product pages. With them, the assistant knows which product the customer is looking at. See Conversation context and history.

How the chat is delivered

The chat component is published by Synerise in two forms.

Files served by Synerise - always the latest release, nothing to update:

npm packages - for applications with a build step, when you want to pin a version and upgrade on your own schedule:

All options described in this article and in the SDK reference work the same way in every form.

Method 1: Adding the chat with a Dynamic Content campaign

Use this method to launch the chat without a release of your website, to test it with a segment of customers first, or to show it only on selected pages. The campaign can be paused at any time.

Creating the template

1. Go to Experience Hub > Dynamic Content and create a template with the template builder.
2. Paste the code below into the template. It adds a launcher button in the bottom-right corner, the chat window, and the script that loads the chat.
   

   <button type="button" id="synerise-assistant-launcher" hidden>Ask the assistant</button>
   <div id="synerise-assistant" hidden></div>
   
   <style>
     #synerise-assistant-launcher {
       position: fixed; right: 24px; bottom: 24px; z-index: 9999;
       padding: 12px 20px; border: 0; border-radius: 999px;
       background: #6d2ed3; color: #fff; font: inherit; cursor: pointer;
     }
     #synerise-assistant {
       position: fixed; right: 24px; bottom: 24px; z-index: 10000;
       width: min(400px, calc(100vw - 32px));
       height: min(720px, calc(100vh - 48px));
     }
   </style>
   
   <script>
     (function () {
       var script = document.createElement("script");
       script.src = "https://web.snrbox.com/ai-shop-assistant/sdk.umd.js";
       script.onload = function () {
         var launcher = document.getElementById("synerise-assistant-launcher");
         var container = document.getElementById("synerise-assistant");
   
         var chat = SyneriseAIShopAssistant.init({
           rootElementId: "synerise-assistant",
           stream: true,
           header: "Shopping assistant",
           autoDetectPageContext: true,
           onLoad: function (result) {
             launcher.hidden = !result.assistantVisible;
           },
           slots: {
             header: {
               closeButton: function (params) {
                 var button = document.createElement("button");
                 button.type = "button";
                 button.setAttribute("aria-label", "Close");
                 button.textContent = "×";
                 button.onclick = function () {
                   params.onClose();
                   container.hidden = true;
                   launcher.hidden = false;
                 };
                 return button;
               }
             }
           }
         });
   
         launcher.addEventListener("click", function () {
           launcher.hidden = true;
           container.hidden = false;
           chat.open();
         });
       };
       document.head.appendChild(script);
     })();
   </script>
   

3. Adjust the texts, colors, and position to your store. To change the chat's own colors and texts, see Customizing the Customer AI Assistant chat.
4. Save the template.

Creating the campaign

1. Create a dynamic content campaign as described in Creating dynamic content and select the template you created.
2. Define the audience. Start with a test segment or your own profile before you show the chat to everyone.
3. Define where the template is inserted. Because the launcher and the window are positioned relative to the browser window, you can insert the template at the end of the page body, for example with the Insert after option and the body selector. See CSS selector basics.
4. Limit the campaign to the pages where the chat should appear, if needed.
5. Test the campaign on your website and activate it.
   Result: Visitors from the audience see the launcher. Clicking it opens the chat with the assistant's greeting.

Method 2: Adding the chat to your website's code

This method is for developers. It gives you full control over where the chat lives on the page and how it interacts with the rest of your store.

Step 1: Add a container and a launcher

Add an element that hosts the chat and a button that opens it. The container must exist when the chat is initialized and must be empty.

<button type="button" id="open-assistant" hidden>Ask the assistant</button>
<div id="synerise-assistant"></div>

Step 2: Load and initialize the chat

Place the script after the Synerise tracking code so that the Web SDK is available when the chat starts.

<script type="module">
  import { init } from "https://web.snrbox.com/ai-shop-assistant/sdk.es.js";

  const launcher = document.getElementById("open-assistant");

  const chat = init({
    rootElementId: "synerise-assistant",
    stream: true,
    header: "Shopping assistant",
    autoDetectPageContext: true,
    onLoad: ({ assistantVisible }) => {
      launcher.hidden = !assistantVisible;
    },
  });

  launcher.addEventListener("click", () => chat.open());
</script>

If your page cannot use module scripts (for example, the code is injected by a tag manager), use the single-file build instead:

<script src="https://web.snrbox.com/ai-shop-assistant/sdk.umd.js" defer></script>
<script defer>
  document.addEventListener("DOMContentLoaded", () => {
    const launcher = document.getElementById("open-assistant");
    const chat = SyneriseAIShopAssistant.init({
      rootElementId: "synerise-assistant",
      stream: true,
      onLoad: ({ assistantVisible }) => {
        launcher.hidden = !assistantVisible;
      },
    });
    launcher.addEventListener("click", () => chat.open());
  });
</script>

What the options do:

• rootElementId - the ID of the container from step 1.
• stream: true - answers appear progressively while the assistant writes. Set it explicitly; see SDK reference.
• header - the name shown in the chat header.
• autoDetectPageContext: true - on product pages with Open Graph tags, tells the assistant which product the customer is viewing.
• onLoad - runs once when the chat knows whether the assistant is available. Show your launcher only then.

The full list of options is in the SDK reference.

Step 3: Choose the assistant

If the workspace has more than one assistant, pass the ID (UUID) of the assistant configuration in the assistantId option. Without it, the default assistant answers.

Step 4: Position the chat

The chat fills its container, so you position and size the container with CSS. A floating window in the corner on desktop and a full-screen view on small screens is a common choice:

#synerise-assistant {
  position: fixed;
  right: 24px;
  bottom: 24px;
  width: 400px;
  height: 720px;
  max-height: calc(100vh - 48px);
  z-index: 10000;
}

@media (max-width: 1023px) {
  #synerise-assistant {
    inset: 0;
    width: auto;
    height: auto;
  }
}

The chat closes when the customer clicks the close button in the header. It stays initialized, so chat.open() reopens the same conversation.

Step 5: Verify the implementation

1. Open a page with the chat. The launcher appears only if the assistant is enabled for your workspace.
2. Click the launcher. The chat opens with the greeting and suggested questions.
3. Ask a product question. The answer appears and product cards follow.
4. Click a product name. The product page opens in a new tab.
5. In Synerise, open your own profile and check the activity: you should see the assistant.conversationStart, assistant.responseGenerated, and assistant.click events. See Customer AI Assistant events.

Method 3: Using the npm packages

For applications built with a bundler, install the package that matches your stack. The vanilla package exposes the same init() function as the files served by Synerise:

npm install @synerise/ai-assistant-sdk

import { init } from "@synerise/ai-assistant-sdk";

const chat = init({
  rootElementId: "synerise-assistant",
  stream: true,
  onLoad: ({ assistantVisible }) => showLauncher(assistantVisible),
});

In React 18 applications, render the AIAssistant component from @synerise/ai-assistant-react instead:

import { AIAssistant } from "@synerise/ai-assistant-react";

export function AssistantPanel() {
  return (
    <AIAssistant
      apiUrl="https://api.synerise.com/agents/v1/ai-assistant"
      displayMode="bordered"
      stream
      disableXSRFToken
      authParams={{ code: SR.auth.trackerKey(), clientUUID: SyneriseTC.uuid }}
      onPromptSuccess={(response) => console.log(response.meta.threadId)}
    />
  );
}

The React and Preact packages render the chat on the client only. Details, including server-side rendering notes and the imperative API, are in the SDK reference.

Going live checklist

• The tracking code is present on every page where the chat appears.
• The assistant is saved in AI Hub and tested in the Preview tab.
• stream: true is set, so answers appear progressively.
• The launcher is shown only when onLoad reports the assistant as available.
• Product pages carry Open Graph tags, or your code sets the page context manually.
• The header name, texts, and colors match your store. See Customizing the Customer AI Assistant chat.
• The chat was tested on a phone: the window fits the screen and the keyboard does not cover the input.
• The assistant events appear on a test profile in Synerise.

What's next

• Configuring Customer AI Assistant in the Synerise platform
• Customizing the Customer AI Assistant chat
• Conversation context and history
• Measuring the Customer AI Assistant
• Troubleshooting the Customer AI Assistant chat