Skip to main contentWatson Assistant web chat

Using a custom launcher

Learn how to use your own method of opening the web chat on your page.

Overview

To integrate with other methods of customer contact, or to better match your brand, you might want to replace the default web chat launcher icon with your own mechanism for opening the web chat window. Web chat makes it easy to hide the built-in default launcher and build your own.

See it in action

Add an instance of web chat configured to behave like this tutorial to this page.

Instructions

First, create an instance of web chat to get the basic embed code.

Adding basic embed code

Now embed the web chat code into your website HTML. The embed code should look something like the code snippet below. Remember to change the integrationID and region values to the values you were given when you created your web chat.

Basic Embed Code

<!doctype html>
<html>
<body>
<script>
  window.watsonAssistantChatOptions = {
    // A UUID like '1d7e34d5-3952-4b86-90eb-7c7232b9b540' included in the embed code provided in Watson Assistant.
    integrationID: 'YOUR_INTEGRATION_ID',
    // Your assistants region e.g. 'us-south', 'us-east', 'jp-tok' 'au-syd', 'eu-gb', 'eu-de', etc.
    region: 'YOUR_REGION',
    // The callback function that is called after the widget instance has been created.
    onLoad: function(instance) {
      instance.render();
    }
  };
  setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>
</body>
</html>

Hiding the default launcher

To hide the default launcher, we need to use the showLauncher configuration option. By setting that option to false, we can render a web chat widget with no launcher icon. (For more information about the web chat configuration options, see Configuration.) The following code snippet updates the configuration options to hide the default launcher.

Updating the configuration to hide the default launcher

<!doctype html>
<html lang="en">
<body>
<script>
  window.watsonAssistantChatOptions = {
    integrationID: "YOUR_INTEGRATION_ID",
    region: "YOUR_REGION",
    serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",

    // Config option to hide the default launcher.
    showLauncher: false,

    onLoad: function(instance) {
      // Render the web chat. Nothing appears on the page, because the launcher is hidden and the web chat window is 
      // closed by default.
      instance.render();
    }
  };

  setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>
</body>
</html>

Adding your launcher

Now we can add the custom launch behavior. To do this, we render our own launch button, and we call the instance.openWindow() instance method when this button is clicked. (For more information about the web chat instance methods, see Instance methods.)

Showing the custom launcher

<!doctype html>
<html lang="en">
<head>
  <style>
    @keyframes slideInRight {
      from {
        transform: translate3d(100%, 0, 0);
        visibility: visible;
      }
    
      to {
        transform: translate3d(0, 0, 0);
      }
    }
    
    button.chatLauncher {
      animation-duration: 0.5s;
      transition-duration: 0.5s;
      position: fixed;
      bottom: 32px;
      right: 32px;
      z-index: 9999;
      border: 4px solid #075cc2;
      padding: 1em;
      border-radius: 8px;
      margin: 0;
      text-decoration: none;
      background-color: #ffffff;
      color: #454545;
      font-family: sans-serif;
      font-size: 1rem;
      cursor: pointer;
      text-align: left;
      -webkit-appearance: none;
      -moz-appearance: none;
      width: 264px;
      opacity: 0;
    }

    button.chatLauncher.open {
      animation-name: slideInRight;
      opacity: 1;
    }

    button.chatLauncher:hover,
    button.chatLauncher:focus {
      background-color: rgb(225, 225, 254);
      border: 4px solid #0053ba;
    }
    
    button.chatLauncher:focus {
      outline: 1px solid #0053ba;
      outline-offset: -4px;
    }
  </style>
</head>
<body>
<!-- We want to hide this element initially, because web chat isn't ready yet. -->
<button type="button" class="chatLauncher" style="display:none;">
  <div>
    <strong>Have questions?</strong> Talk with Karen our Virtual Assistant.
  </div>
</button>
<script>
  window.watsonAssistantChatOptions = {
    integrationID: "YOUR_INTEGRATION_ID",
    region: "YOUR_REGION",
    serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",

    showLauncher: false,
    onLoad: function(instance) {
      // Select the button element from the page.
      const button = document.querySelector('.chatLauncher');
  
      // Add the event listener to open your web chat.
      button.addEventListener('click', function clickListener() {
        instance.openWindow();
      });
  
      // Render the web chat. Nothing appears on the page, because the launcher is
      // hidden and the web chat window is closed by default.
      instance.render().then(function() {
        // Now that web chat has been rendered (but is still closed), we make the
        // custom launcher button visible.
        button.style.display = 'block';
        button.classList.add('open');
      });
    }
  };

  setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>
</body>
</html>