Top Secret Virtual Assistant Launcher Hacks

This post originally posted on the IBM Watson Apps Community, under the title Top Secret Virtual Assistant Hacks on September 24, 2020.

Photo by Kristina Flour on Unsplash

I usually start these blog posts talking about the smart people that I work with. Today I learned something new, with some guidance from our IBM Watson development team. It has to do with some top-secret, virtual assistant launcher hacks. OK — none of this is really top secret stuff, but it is the kind of thing that is good to know — and the type of thing that can make your virtual assistant look so much more professional and useful. I got into this because one of my current customers had a COVID-19 chatbot, which has its own launcher, with a disclaimer page. What it didn’t have, was the ability to change the color scheme of the launcher button. So we wanted to do a more standard launcher.

Step 1 — Set up the Color Scheme

Go into your Watson Assistant instance, and look at your Assistants. Now go into one of your Assistants, and look at what is set up. You probably see a dialog skill, and maybe even a search skill. You should also see some integrations. If your assistant is deployed on a web page, you will see the Web Chat integration listed here. Click on it and you will see some particulars about your Assistant.
The first tab that you see is the Style tab. This contains all of your choices for colors and avatar images. Set this up with colors that match your theme — use one of the HTML color pickers that you might find online. You can also add an icon, but be aware of a few things. One — the icon needs to be at a web address where it can be found and read — so it probably should be a file on your website. It can’t be just a JPG that you have on your hard drive (or a picture of your dog — I was hoping for that….).

A small dog icon?

The other thing is that the image needs to be between 64 x 64 and 100 x 100 pixels in size. Try to keep it square (or it may get distorted).
The next tab is the Home Screen tab. This is new stuff. Turn it on and see how the home screen will pull your users in, and provide them with some common examples of some things that they might ask about. This is really useful for deployments where the users may not be sure of the types of things that they can ask your assistant. It might confuse some users, who might think that the three options that you provide are the ONLY things that your assistant can talk about. Use it if you think it will help your user community engage more effectively.
The third tab is the Live Agent tab. If you have been using this to help you connect into your existing service desk infrastructure, then keep on using it. Right now, it will connect in with Zendesk, Intercom and Salesforce, but by the time you read this, it may connect with other service desk solutions as well. Turn it on and take a look at the options that you have.
The next tab is the Security Tab. This allows you to use some public keys to encrypt data being sent to and from your assistant. If conversational security is a big issue for you, then you will want to read some more about how to secure your web chat.
The final tab is the Embed tab. This is where the magic happens. Based on everything that you have set up, a small chunk of code is generated for you, in the copy and paste section of the screen. You will now cut and paste this chunk of code into the HTML body of the web pages where you want your virtual assistant to be present. This is really easy to do — we typically suggest doing it at the bottom of the page — where you can easily find it if you need to make changes. (Note: This is what we call a “tease” — where we hint about things you will have to do later.)
All of this will get you a basic virtual assistant launcher, with the color scheme that you want, and possibly with a home screen or live agent enabled. This is all of the basic stuff. The best part of this is, if you just follow the directions here, you don’t need to be a software developer to put any of these things into place.

Advanced Assistant Trickiness — Part 1

Now let’s work on getting a disclaimer going with our virtual assistant. If we know about this disclaimer feature, then maybe we’re also aware of the documentation on the feature, that describes how to get a disclaimer screen for your assistant. Check out that Configuration Options Object in the documentation. There are a lot of different things that you can change. We’re interested in that last one, the disclaimer object. Now we have the knowledge that we need for our first changes to our assistant.
So go look at your web page, and if you already had code inserted that deployed your assistant on the web page, we'll want to comment it out. Don't delete it - you might not end up liking what you did, and want to bring back the original. So for those of you who are unfamiliar with how to comment this out, first we need to find that block of text that has the existing Watson Assistant script. It should look like this:

<script>
window.watsonAssistantChatOptions = {
integrationID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
region: "us-east",
serviceInstanceID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
covidStrings: {
greeting: "Hello, I&apos;m",
watson_assistant: "Watson Assistant",
disclaimer_title: "Disclaimer",
disclaimer_body: "This tool is intended to provide information based on currently available CDC and other public information to help you make decisions about seeking appropriate medical care and help provide you with the resources necessary for your visit. This system is not intended for the diagnosis or treatment of disease or other conditions, including COVID–19, and you should not provide any personally identifying or private health information.",
disclaimer_accept: "I accept",
disclaimer_no_accept: "I do not accept",
// Only used for "large" or "reveal" launchers.
launcher_title: "Got COVID-19 questions?",
// Only used for "large" or "reveal" launchers.
launcher_body: "Chat with <b>our virtual assistant</b>",
launcher_alt_text:"Watson Assistant can help you learn move about planning a visit, preparing for your appointment and COVID-19",
},
// You can choose a 'small', 'large' or a 'reveal' launcher. On a phone sized device we will always show the 'small' launcher.
// The 'reveal' launcher introduces itself in 'large' mode, and then animates down to 'small' mode after a period of time. Defaults to 'small', but 'reveal' and 'large' are recommended.
covidLauncherVersion: 'large',
onLoad: function (instance) {
instance.render();
},
};
setTimeout(function(){
const t=document.createElement('script');
t.src='https://webchat.global.assistant.watson.appdomain.cloud/covid/webchat.js';
document.head.appendChild(t);});
</script>

Note those covidStrings parameters and the fact that the script being called is specific for covid (it is not the usual call to loadWatsonAssistantChat.js). You will want to remember that disclaimer_body parameter - that is the specific language used in your disclaimer. You will need to use that again in the new code that you use. Also note the launcher_title and launcher_body parameters. Those will be needed for the next level of advanced trickiness.

Now it's time to make some changes. Before doing this, it is wise to follow the wisdom of old software people - they make copies of EVERYTHING before they change things. So make a copy of that original HTML file, and save it somewhere safe, so you can use it to restore things to normal if you make mistakes with your modifications.

We are now going to comment this out, by putting this line before the script:

<!-- OLD WATSON ASSISTANT SCRIPT

and this line after the script:

END OLD WATSON ASSISTANT SCRIPT  -->

This has the effect of leaving the text in there, but not having it execute. So now we need to paste in our new code, and we want this to execute. So we will paste the block of code from the Embed tab into the HTML file after that last comment above. Your code will probably look like this:

<script>
window.watsonAssistantChatOptions = {
integrationID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
region: "us-east",
serviceInstanceID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
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>

Now to get our disclaimer to work, we will need to insert the disclaimer parameters into this new block of code, and we'll do it right after the ServiceInstanceID line. It should look something like this now:

<script>
window.watsonAssistantChatOptions = {
integrationID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
region: "us-east",
serviceInstanceID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
disclaimer: {isOn: true, disclaimerHTML: "This tool is intended to provide information based on currently available CDC and other public information to help you make decisions about seeking appropriate medical care and help provide you with the resources necessary for your visit. This system is not intended for the diagnosis or treatment of disease or other conditions, including COVID–19, and you should not provide any personally identifying or private health information."},
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>

Go ahead and give that webpage a try. You will see your custom colors, and your custom disclaimer. Not bad so far.

Advanced Assistant Trickiness — Part 2

Now let’s go for the next step — let’s build ourselves a custom assistant launcher. You can find the custom launcher tutorial for this in the documentation, or you can keep reading this blog and see how I did it. It’s only a bit more complex, and it still doesn’t really require any software coding skills.

To do this, we’ll need to understand that there are two different “sections” of your HTML page. The top part has a <head> section, which is all of the content in between the <head> and </head> tags. All of that is considered the <head> section - and this is usually the information that is used by the web page, but never really displayed. We will be putting some <style> data in this section. The bottom part is the <body> section (between the <body> and </body> tags), and this is where the web page content is usually found. This is where we will update the Watson Assistant deployment scripts (which we’ve already put in the body).

Lets do the <style> section first. Go into your web page, and at the bottom of the <head> section, paste in this style code:

<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 #000000;
padding: 1em;
border-radius: 8px;
margin: 0;
text-decoration: none;
background-color: #aea500;
color: black;
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: #645f05;
color: white;
border: 4px solid #0053ba;
}
button.chatLauncher:focus {
outline: 1px solid #0053ba;
outline-offset: -4px;
}
</style>

Some things to note from this.

  • In the section where button.chatbotLauncher is defined, look for the definition of background-color, color, and font-family. These will define the color of the button (background-color), the color of the text (color), and the text font used (font-family). You should change these to match the look and feel of your website.
  • In the section where button.chatLauncher:focus is defined, see how the button color (background-color) and text color (color) are changed when a user hovers over the button.
  • If you are interested in any of these other settings, and just want to learn more about CSS stylesheets, you may want to check out one of the online guides for CSS.

Now let’s go and do the changes to the <body> section. We are going to change the <script> that is already there, and we are going to add a <button> before the <script>. Find your previous <script> that was added to enable the Watson Assistant on your webpage, and comment it out. Then replace it with this one:

<button type="button" class="chatLauncher" style="display:none;">
<div>
Have questions? Talk with RoboTox our Virtual Assistant.
</div>
</button>
<script>
window.watsonAssistantChatOptions = {
integrationID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
region: "us-east",
serviceInstanceID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
disclaimer: {isOn: true, disclaimerHTML: "This tool is intended to provide information based on currently available CDC and other public information to help you make decisions about seeking appropriate medical care and help provide you with the resources necessary for your visit. This system is not intended for the diagnosis or treatment of disease or other conditions, including COVID–19, and you should not provide any personally identifying or private health information."},
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>

Some things to note from this block:

  • We added a <button> block. The text in between the <div> tags is what will be displayed on your button. You can display ANY kind of HTML text you want.
  • We also added the showLauncher: false line, and a new onLoad: function(instance) block of code. This hides the default assistant launcher, and then displays YOUR custom launcher.

Now give your web page a try. Doesn’t that virtual assistant look fantastic? It only took a few minutes to make sure that the look and feel of your site was maintained, and you now have a user assistant that fits seamlessly into the whole website, providing guidance and support for your users and customers.

For extra credit, I tried to slam my dog’s picture into the button, by inserting an <img> tag into the button instead of text (check out some online guidance for more about using <img> tags in HTML). It worked — but the result wasn’t as good as I had hoped. It just looked wrong — but I could see how a circular button, with a picture, might actually look pretty good.

Helpful user hint: If you are having difficulty in deploying your virtual assistant on your web page, first trying deploying it onto an empty, or blank, HTML file. Just have your code in the head and in the body, and your launcher will appear on a blank white page all by itself. Then you can make changes and try things without messing up your web pages.

AI Technical Leader — Customer Success Management — Driving real business value from AI technology

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store