vania-janet/multiturn-rag-retrieval-data huggingface dataset:
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



 Web chat overview 

Learn more about the web chat that you can add to your company website.

Web chat is a code snippet that you can immediately embed in your website.

When you build a custom user interface for your assistant, you spend a lot of time and effort writing code to solve typical UI problems. For example, you must keep up with browser support changes, manage scrolling behavior, validate input, and design the layout and styling. The time you spend designing and maintaing a UI can be better spent building a quality assistant instead. When you use the web chat integration, you can rely on us to manage the user interface, so you can focus on designing conversational exchanges that address the unique business needs of your customers. Cutting-edge functionality from IBM Design and Research is incorporated into the web chat to deliver an exceptional user experience.

For more information about how to deploy the web chat, see [Integrating the web chat with your website](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chat).



 Browser support 

The web chat supports a variety of devices and platforms. As a general rule, if the last two versions of a browser account for more than 1% of all desktop or mobile traffic, the web chat supports that browser.

The following list specifies the minimum required browser software for the web chat (including the two most recent versions, except as noted):



* Google Chrome
* Apple Safari
* Mobile Safari
* Chrome for Android
* Microsoft Edge (Chromium and non-Chromium)
* Mozilla Firefox
* Firefox ESR (most recent ESR only)
* Opera
* Samsung Mobile Browser
* UC Browser for Android
* Mobile Firefox



For optimal results when rendering the web chat on mobile devices, the <head> element of your web page must include the following metadata element:

<meta name="viewport" content="width=device-width, initial-scale=1" />





 Global audience support
How the web chat works 

The web chat provides an easy-to-use chatbot interface that you can add to your website without writing any code.

After you add the web chat script to your website, your customers will see a launcher icon that they can click to open the chat window and start a conversation with the assistant. The appearance of the launcher icon adapts to desktop and mobile browsers.

![web chat launcher in desktop browser](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-desktop-highlighted.png)

When a customer clicks the launcher, the web chat window opens, initially displaying the home screen. The home screen displays a greeting and an optional set of suggested conversation starters for common questions and problems. The customer can either click a conversation starter or type a message in the input field to start the conversation with the assistant.

![web chat example home screen](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-home-screen-lendyr.png)

The appearance and behavior of the launcher icon, the home screen, and most other aspects of the web chat can be configured and customized to match your website style and branding. For more information, see [Configuring the web chat](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-config).



 Launcher appearance and behavior 

The web chat launcher welcomes and engages customers so they know where to find help if they need it. By default, the web chat launcher appears in a small initial state as a circle in the bottom right corner:

!
The script calls JavaScript code that is hosted on an IBM site and creates an instance of a widget that communicates with the assistant.
4. Click the ![Copy icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/copy-icon.png)Copy to clipboard icon to copy the embed script to the clipboard.
5. Edit the HTML source for the web page where you want the web chat widget to appear. Paste the code snippet into the page. Paste the code as close as possible to the closing </body> tag to ensure that your page renders faster.

Do not modify the integrationID or region property values in the generated embed script.

If you aren't ready to add the web chat to a live website, you can quickly test it using a local HTML file. Use this HTML code as the source for a test page:

<html>
<head></head>
<body>
<title>My Test Page</title>
<p>The body of my page.</p>

</body>
</html>

Just copy this code into a file with the .html extension, and replace the script element with the embed script you copied in the previous step.

The identifiers in the embed script (such as integrationIDserviceInstanceID) are not considered secret, and are visible to anyone who has access to your website. For more information, see [Security](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-architectureweb-chat-architecture-security).
6. If the system that hosts your website has limited Internet access (for example, if you use a proxy or firewall), make sure the URLs that host the web chat are accessible.
For more information, see [Showing more suggestions](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-chatdeploy-web-chat-alternate).
8. Optional: To secure the web chat, click the Security tab. For more information, see [Securing the web chat](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-chatdeploy-web-chat-security).
9. Click the Embed tab.

A code snippet is displayed that defines the chat window implementation. You will add this code snippet to your web page. The code snippet contains an HTML script element. The script calls JavaScript code that is hosted in your deployed cluster environment. The code creates an instance of a widget that communicates with the assistant. The generated code includes a region and unique integration ID. Do not change these parameter values.
10. Copy the script HTML element.
11. If you made any customizations, click Save and exit. Otherwise, click Close.

The web chat instance is created as soon as you click the Create button, and does not need to be saved.
12. Open the HTML source for a web page on your website where you want the chat window to be displayed. Paste the code snippet into the page.

Paste the code as close to the closing </body> tag as possible to ensure that your page renders faster.

The following HTML snippet is the source for a test page that you can copy and save as a file with a .html extension for testing purposes. You would replace the script element block here with the script elements you copied from the web chat integration setup page.

<html>
<head></head>
<body>
<title>My Test Page</title>
<p>The body of my page.</p>

</body>
</html>
13. Refresh the web page.
Adding the web chat to your mobile application 

If you have a mobile application built on a mobile framework such as iOS, Android, or React Native, you can use a WebView with a JavaScript bridge to communicate between your app and the Watson Assistant web chat.

Using WebViews with a JavaScript bridge is a common pattern with a similar implementation for all mobile frameworks.



 Including the web chat as a WebView 

You can include the web chat interface as part of a page of your mobile app, or as a separate panel that your app opens. In either case, you must host an HTML page that includes the web chat embed script, and then include that page as a WebView in your app.

In the embed script, use the showLauncher option to hide the web chat launcher icon, and the openChatByDefault option to open the web chat automatically when the page loads. In most cases, you will also want to use the hideCloseButton option and use the native controls of your app to control how the web chat page or panel closes. For more information about the configuration options you can specify in the embed script, see the [Web chat API reference](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration).

The following example shows an embed script that includes these configuration options:

<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<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",
instance.render();
}
};







 Security measures 

The web chat integration undergoes tests and scans on a regular basis to find and address potential security issues, such as cross-site scripting (XSS) vulnerabilities.

Be sure to run your own security reviews to see how the web chat fits in with your current website structure and policies. The web chat is hosted on your site and can inherit any vulnerabilities that your site has. Only serve content over HTTPS, use Content Security Policy (CSP), and implement other basic web security precautions.
If you want to make more advanced customizations, you can make the following types of changes:



* Change the launcher icon that is used to open the web chat widget. For a tutorial the shows you how, see [Using a custom launcher](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-launcher).
* Change how the web chat widget opens. For example, you might want to launch the web chat from some other button or process that exists on your website, or maybe open it in a different location, or at a different size. For a tutorial that shows you how, see [Render to a custom element](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-example-element).
* Hide the launcher icon entirely and automatically start the web widget in open state, at its full length. For more information, see the [openChatByDefault method](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationconfigurationobject).
* Hide the close button so users cannnot close the web chat widget. For more information, see the [hideCloseButton method](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationconfigurationobject).







 Change the conversation 

The core of the conversation is defined in your skill. If you use more than one integration type, focus on defining an engaging conversation in the underlying skill. The same skill is used for all integrations. To customize the conversation for the web chat only, you can take the following actions:



* Update the text of a message before it is sent or after it is received, such as to hide personally-identifiable information.
* Pass contextual information, such as the customer's name, from the web chat to the underlying skill.
The user receives a link that forwards them to your organization's website where a connection to an agent response can be started within web chat. For more information, see [Adding a Channel transfer response type](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-channel-transfer).







 3.5.0 

Release date: 17 February 2021



* Session history (beta): Web chat session history (beta) is now available. This feature makes it possible to maintain conversation history and context when customers refresh the page or navigate to a different page on the same website. For more information about this beta feature, see [Session history (beta)](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-session-history).







 3.4.1 

Release date: 2 February 2021



* Made an accessibility enhancement to the chat history. Now, you can use keys to navigate the messages by clicking the chat history, pressing Enter, and then using the arrow keys to move from one message to the next.
* The instance.updateAssistantInputFieldVisibility() method was added. You can use it to hide or show the text input field. For example, you might use the pre:receive event to check whether an options response type is being returned and if so, hide the text field so the user is forced to pick one of the available options only.
* The instance.getState() method was added. You can use it to check for specific conditions, such as isWebChatOpen, before you perform an action that might rely on the condition being true.



For more information about the new methods, see [Instance methods](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methods).





 3.3.2 

Release date: 17 December 2020



* Addressed accessibility issues.







 3.3.1 

Release date: 3 December 2020
For more information, see [Applying advanced customizations](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-config).
4. Click the icon to open the chat window and talk to your assistant.

![Web chat window](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/web-chat-window.png)
5. Paste the code snippet into each web page where you want the assistant to be available to your customers.

You can paste the same script tag into as many pages on your website as you want. Add it anywhere where you want users to be able to reach your assistant for help. However, be sure to add it only one time per page.
6. Submit test utterances from the chat widget that is displayed on your web page to see how the assistant responds.

No responses are returned until after you create a dialog skill and add it to the assistant.

If the Connect to agent button is displayed and you don't have human agent support configured, you can hide it by changing the Suggestions configuration. For more information, see [Showing more suggestions](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-alternate).

If you don't extend the session timeout setting for the assistant, the dialog flow for the current session is restarted after 60 minutes of inactivity. This means that if a user stops interacting with the assistant, after 60 minutes, any context variable values that were set during the previous conversation are set to null or back to their initial values.



A developer can use APIs to apply more advanced customizations to the style of the web chat. For more information, see [Applying advanced customizations](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-config).





 Launcher appearance and behavior
* Add a home screen: Ease your customers into the conversation by adding a home screen to your web chat window. The home screen greets your customers and shows conversation starter messages that customers can click to submit to the assistant. For more information about this beta feature, see [Adding a home screen](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-home-screen).







 2.3.0 

Release date: 10 August 2020



* Introducing Suggestions: Enable this beta feature to show a helper icon in the chat that customers can click to see alternate topics or to connect to an agent. For more information, see [Showing more suggestions](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-alternate).
* Search results are now expandable: When search results are displayed in the web chat, users can click Show more to see more of the search result text.







 2.2.0 

Release date: 29 July 2020



* Introduced the instance.writeableElements() method: The instance.writeableElements() method gives you zones in the web chat user interface where you can embed your own content. For example, you can add content to the end of the header where it is displayed even as the chat content changes. Or you can add custom content that is displayed before the welcome node. For more information, see [Instance methods](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodswriteableelements).
* Gave the Send button a new look

Changed the icon from ![Arrow send icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-send-old.png) to !
For more information about the home screen, see [Adding a home screen](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-home-screen). For more information about how to customize it, see [HTML content](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-renderhtml)



The web chat is embedded directly on your page, not inside an iframe. Therefore, the cascading style sheet (CSS) rules for your website can sometimes override the web chat CSS rules. The web chat applies aggressive CSS resets, but the resets can be affected if your website uses the !important property in elements where style is defined.



 Passing values 

Here are some common tasks you might want to perform:



* [Setting and passing context variable values](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-configweb-chat-config-set-context%7D)
* [Adding user identity information (if you don't enable security)](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-configweb-chat-config-userid)



For a tutorial that describes how to set context values from the web chat, see [Setting context](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-setting-context).



 Setting and passing context variable values 

A context variable is a variable that you can use to pass information to your assistant before a conversation starts. It can also collect information during a conversation, and reference it later in the same conversation. For example, you might want to ask for the customer's name and then address the person by name later on.

The following script preserves the context of the conversation. In addition, it adds an $ismember context variable and sets it to true.
For more information, see the [Using a custom launcher tutorial](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-launcher).
* Changing the size or position of the chat window that is displayed when users click the launcher button. For more information, see the [Render to a custom element tutorial](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-example-element).



14. Click the icon to open the chat window and talk to your assistant.

![Web chat window](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/web-chat-window.png)

The traffic to and from the web chat is sent between the instance that is hosted by your deployed cluster environment and the web page where you embed the web chat.
15. Paste the code snippet into each web page where you want the assistant to be available to your customers.

You can paste the same script tag into as many pages on your website as you want. Add it anywhere that you want users to be able to reach your assistant for help. However, be sure to add it only one time per page.
16. Submit test utterances from the chat widget that is displayed on your web page to see how the assistant responds.

No responses are returned until after you create a dialog skill and add it to the assistant.

If you don't extend the session timeout setting for the assistant, the dialog flow for the current session is restarted after 60 minutes of inactivity. This means that if a user stops interacting with the assistant, after 60 minutes, any context variable values that were set during the previous conversation are set to null or back to their initial values.
You add this script to your website in the next section, [Deploy your assistant in production](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-snippet).
13. If you made any customizations, click Save and exit. Otherwise, click Close.

The web chat instance is created as soon as you click the Create button, and does not need to be saved.







 Deploy your assistant in production 



1. If the system that hosts your website has limited Internet access (for example, if you use a proxy or firewall), make sure the following URLs are accessible:



* https://web-chat.global.assistant.watson.appdomain.cloud: Hosts the code for the web chat widget, and is referenced by the script you embed on your website.
* https://integrations.{location}.assistant.watson.appdomain.cloud: Hosts the web chat server, which handles communication with your assistant. Replace {location} with the location of the data center where your service instance is located, which is part of the service endpoint URL. For more information, see [Finding and updating the endpoint URL](https://cloud.ibm.com/docs/watson?topic=watson-endpoint-changeendpoint-find-update).



2. Open the HTML source for a web page on your website where you want the chat window to be displayed. Paste the code snippet into the page.

Paste the code as close to the closing </body> tag as possible to ensure that your page renders faster.

The following HTML snippet is the source for a test page that you can copy and save as a file with a .html extension for testing purposes. You would replace the script element block here with the script elements you copied from the web chat integration setup page.

<html>
<head></head>
<body>
<title>My Test Page</title>
<p>The body of my page.</p>

</body>
</html>
3.
For more information about the suggestions feature, see [Showing more suggestions](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-alternate). For more information about the home screen, see [Configuring the home screen](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-home-screen).
* onError callback: The new onError callback option in the web chat configuration enables you to specify a callback function that is called if errors occur in the web chat. This makes it possible for you to handle any errors or outages that occur with the web chat. For more information, see [Listening for errors](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationonerror-detail).
* Session ID available in widget state: The state information returned by the getState() instance method now includes the session ID for the current conversation. For more information, see [instance.getState()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsgetState).
* IBM watermark: The web chat can now display a Built with IBM Watson watermark to users. This watermark is always enabled for any new web chat integrations on Lite plans. For more information, see [Create a web chat instance to add to your website](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-task).
* Fixes to rendering of list items: The rendering of HTML list items in the web chat widget has been updated.







 4.1.0 

Release date: 8 April 2021



* Home screen now generally available: Ease your customers into the conversation by adding a home screen to your web chat window. The home screen greets your customers and shows conversation starter messages that customers can click to easily start chatting with the assistant.