vania-janet/multiturn-rag-retrieval-data huggingface dataset:
<meta name="viewport" content="width=device-width, initial-scale=1" />





 Accessibility 

IBM strives to provide products with usable access for everyone, regardless of age or ability.

The web chat integration complies with the [Web Content Accessibility 2.1 Level AA](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-21/) standard. It is tested with both screen readers and automated tools on a continual basis.





 Language support 

By default, the web chat displays hardcoded labels and messages in English, but support is built in for all of the languages supported by Watson Assistant. You can also choose from a wide selection of locales to customize the display of strings like dates and times for global audiences.

In whichever language you are using, you can also customize the text of any hardcoded strings.

For more information, see [Supporting global audiences](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-develop-global).





 Security 

By default, all messages that are sent between the web chat and the assistant are encrypted using Transport Layer Security (TLS). You can enable the web chat security feature if you need more robust protection.

The web chat embed script that you include on your website contains unique identifiers (such as the integration ID and service instance ID) that enable the web chat to connect with your assistant. These identifiers are not considered secret, and are visible to anyone who has access to your website. Anyone who has these IDs could use them to send messages to your assistant and receive its replies. However, these IDs cannot be used to log in to your account, make any changes to your assistant, or retrieve logs or analytics information about your assistant.

If you are concerned about unauthorized access to your assistant, you can enable the web chat security feature for additional security, such as verifying message origin and authenticating users. Enabling the security feature requires additional development work on your website.
![Shows the chat bot preview in a fake web page](https://cloud.ibm.com/docs-content/v1/content/f16b1f78a92498247223b337bd9303c2758b9ba8/discovery-data/images/tut-convo-assis-intro-5.png)

Figure 4. Web chat preview

A preview of the web chat as it would be displayed in a web page is shown.
7. Click Create to create the assistant and the corresponding web chat app.



After a congratulatory message, the home page for your new assistant is displayed.

Zoom

![Shows the assistant page](https://cloud.ibm.com/docs-content/v1/content/f16b1f78a92498247223b337bd9303c2758b9ba8/discovery-data/images/tut-convo-assis-intro-6.png)

Figure 5. Assistant home page





 Step 2: Create an action 

Create a single action that can recognize questions about the latest research papers from the US Federal Reserve Economic Data (FRED) website.

In a real world scenario, you might want your assistant to answer questions about the products in your catalog or about insurance plan options or anything else. You can complete similar steps to teach the assistant to recognize when a customer is asking about a particular subject.



1. From the navigation panel, click Actions.

Zoom

![Shows the Watson Assistant navigation panel](https://cloud.ibm.com/docs-content/v1/content/f16b1f78a92498247223b337bd9303c2758b9ba8/discovery-data/images/tut-convo-action-0.png)

Figure 6. Actions menu

The Actions page is displayed.

Zoom

![Shows the actions introduction page.]
For more information about implementing chat transfers, see [Adding a Connect to human agent response type](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-overviewdialog-overview-multimedia-add). For more information about the contains() SpEL expression method, see [Expression language methods](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-methods).









 Web chat: Reusing the JWT for webhook authentication 

You can use the same JSON Web Token (JWT) that was used to secure your web chat to authenticate webhook calls. If you specify a token in the identityToken property when you add the web chat to your web page, the token is stored in a private variable named context.integrations.chat.private.jwt. For more information about passing a JWT, see [Enable security](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-chatdeploy-web-chat-security-task).



1. From your dialog skill, open the Options>Webhooks page.
2. Click Add authentication.
3. Without adding any values to the fields in the Basic authorization modal that is displayed, click Save.

An Authorization header is added for you.
4. In the Header value field, add $integrations.chat.private.jwt.
For a real application, you need to define some more interesting intents, some entities, and a more complex dialog that uses them both. When you have a polished version of the assistant, you can integrate it with web sites or channels, such as Slack, that your customers already use. As traffic increases between the assistant and your customers, you can use the tools that are provided in the Analytics page to analyze real conversations, and identify areas for improvement.



* Complete follow-on tutorials that build more advanced dialogs:



* Add more dialog nodes to design complex conversational exchanges. See [Building a complex dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-tutorial).
* Learn techniques for getting customers to share information that the assistant needs before it can provide a useful response. See [Adding a node with slots](https://cloud.ibm.com/docs/assistant?topic=assistant-tutorial-slots).
Service desk transfer support continues to be a beta feature. For more information, see [Integrating with your own website](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chat).

Secure your web chat
: Enable the beta security feature of web chat so that you can verify that messages sent to your assistant come from only your customers and can pass sensitive information to your assistant.





 27 April 2020 

Add personality to your assistant in web chat
: You can add an assistant image to the web chat header to brand the window. You can add an avatar image that represents your assistant or a brand logo, for example. For more information, see [Integrating with your own web site](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chat).

Know your plan
: Now your service plan is displayed in the page header. And if you have a Plus Trial plan, you can see how many days are left in the trial.





 21 April 2020 

Fuzzy matching support was expanded
: Added support for stemming and misspelling in French, German, and Czech dialog skills. This enhancement means that the assistant can recognize an entity value that is defined in its singular form but mentioned in its plural form in user input. It also can recognize conjugated forms of a verb that is specified as an entity value.

For example, if your French-language dialog skill has an entity value of animal, it recognizes the plural form of the word (animaux) when it is mentioned in user input. If your German-language dialog skill has the root verb haben as an entity value, it recognizes conjugated forms of the verb (hast) in user input as mentions of the entity.





 2 April 2020 

New and improved access control
: Now, when you give other people access to your Watson Assistant resources, you have more control over the level of access they have to individual skills and assistants. You can give one person read-only access to a production skill and manager-level access to a development skill, for example.
To test the updates in a version release of web chat before you apply the version to your live web chat, follow these steps:



1. Lock the web chat that is running in your production environment to a specific version.
2. Embed your web chat deployment into a new page in a test environment, and then override the version lock setting. For example, specify clientVersion="latest".
3. Test the web chat, and make adjustments to the configuration if necessary.
4. Update your production deployment to use the latest version and apply any other configuration changes that you determined to be necessary after testing.



For more information about features that were introduced in previous web chat versions, see the [Web chat release notes](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-release-notes-chat).





 Billing 

Watson Assistant charges based on the number of unique monthly active users (MAU).

The web chat uses the following methods to track users:



* You can pass in a de—identified user ID either as part of a secure JWT or as a string passed to instance.updateUserID method. If you are using advanced security features, the user ID is derived from the sub claim in the JWT.
* If you do not pass an identifier for the user when the session begins, the web chat creates one for you. It creates a first-party cookie with a generated anonymous ID. The cookie remains active for 45 days. If the same user returns to your site later in the month and chats with your assistant again, the web chat integration recognizes the user. And you are charged only once when the same anonymous user interacts with your assistant multiple times in a single month.





 Apple devices 

On Apple devices, the Intelligent Tracking Prevention feature automatically deletes any client-side cookie after 7 days. This means that if an anonymous customer accesses your website and then visits again two weeks later, the two visits are treated as two different MAUs.

To avoid this problem, use a server-side first-party cookie in your web application.
Web chat development tutorials 

The tutorials in this section provide detailed examples, including code snippets, showing customizations that you can implement using the web chat API.

Each tutorial includes links to a [GitHub repository](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/) where you can download complete working code for the example. You can run this code to see the customization in action, adapt it for your own web chat implementation, or use it as a guide for similar customizations of your own.

The GitHub repository also includes additional tutorials and examples that have not yet been added to this documentation, so feel free to browse.
* You can choose to use a different base Carbon Design theme. The supported base themes are color themes that are defined by [IBM Carbon Design](https://www.carbondesignsystem.com/guidelines/color/usage/). For more information, see [Theming](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodstheming).
* Alternatively, you can set individual variables within the theme to customize specific UI elements. For example, the text that is displayed in the chat window uses the fonts IBMPlexSans, Arial, Helvetica, sans-serif. If you want to use a different font, you can specify it by using the instance.updateCSSVariables() method.
* Apply style settings to user-defined response types. If you enable the web chat to return custom response types, be sure to apply existing or custom CSS classes to them. For more information, see [Custom content](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-render).
* Change the style of the home screen that can be displayed when the web chat is opened. For more information about the home screen, see [Adding a home screen](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-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:
A sample web page is displayed that includes a chat icon ![Chat icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/chat.svg).
2. Click the chat icon to open the web chat window.

Zoom

![Shows web chat welcome message](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/tut-convo-test-2.png)

Figure 18. Web chat welcome message
3. Enter the following text question:

What project types are available?

The correct answer is returned and it includes a link to the product documentation.

Zoom

![Shows a preview of the assistant where the test question is answered](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/tut-neural-answer.png)

Figure 19. Web chat returns search response
4. Submit a question that wasn't used as a query example when you created the action.

How do you define synonyms in Watson Discovery?

A detailed answer is returned.

Zoom

![Shows another preview of the assistant where the test question is answered](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/tut-neural-answer2.png)

Figure 20. Web chat returns a detailed answer
5. Optionally ask the assistant other questions.
* 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. For examples of how to complete common tasks, see [Passing values](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-web-chat-configweb-chat-config-context).
* Change the language that is used by the web chat. For more information, see [Global audience support](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-chatdeploy-web-chat-global-support).
* Render your own custom response types inside the web chat widget, including responses that incorporate code from your website at run time. For a tutorial that shows you how, see [Creating a custom response](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-user-defined-response).
* Use React portals to render your custom response type as part of your application. For a tutorial that shows you how, see [Custom responses with React](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-react-portals).







 Change the look of the web chat 

You can make simple changes to the color of things like the text font and web chat header from the Style tab of the web chat configuration page. To make more extensive style changes, you can set the CSS style color theme to a different theme or specify your own theme.



* You can choose to use a different base Carbon Design theme. The supported base themes are color themes that are defined by [IBM Carbon Design](https://www.carbondesignsystem.com/guidelines/color/usage/). For more information, see [Theming](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodstheming).
[development icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/development-icon.png)Tutorial: For a tutorial that shows you how to implement a custom launcher, see [Using a custom launcher](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-launcher).

Keeping the web chat always open
: If you want to keep the web chat always open on your page, use the [openChatByDefault](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationoptionsopenChatByDefault) configuration open to render the page with the chat window open, and the [hideCloseButton](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationoptionshideCloseButton) option to prevent customers from closing it.

Changing the size or position of the web chat
: Your website design might require that you change where and how the web chat window renders on your website. For example, you might want it to appear in a different position on the page, at a different size, or nested within another element on the page.

To change the size of the web chat window, you can use the [updateCSSVariables()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdatecssvariables) instance method to modify the CSS styling.

If you need to change the position of the web chat window, or you need to change the size beyond the limits allowed in the CSS, you can use a custom DOM element to contain the web chat window. To do this, use the [element](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationoptionselement) configuration option.
* Session history now generally available: Session history allows your web chats to maintain conversation history and context when users refresh a page or change to a different page on the same website. It is enabled by default. For more information about this feature, see [Session history](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-session-history).

Session history persists within only one browser tab, not across multiple tabs. The dialog provides an option for links to open in a new tab or the same tab. See [this example](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-session-historyTutorial1) for more information on how to format links to open in the same tab.

Session history saves changes that are made to messages with the [pre:receive event](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventsprereceive) so that messages still look the same on rerender. This data is only saved for the length of the session. If you prefer to discard the data, set event.updateHistory = false; so the message is rerendered without the changes that were made in the pre:receive event.

[instance.updateHistoryUserDefined()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdateHistoryUserDefined) provides a way to save state for any message response. With the state saved, a response can be rerendered with the same state. This saved state is available in the history.user_defined section of the message response on reload. The data is saved during the user session. When the session expires, the data is discarded.
If your mobile application needs to call a web chat instance method, you must call the method by sending an event from the app to the WebView using the JavaScript bridge. Similarly, if you need to run code in your mobile application in response to behavior in the web chat, you can send an event through the JavaScript bridge from the web chat to your mobile application.

You can make use of the user_defined response type and the customResponse event to drive behavior on your mobile application. However, you must strip the event.data.element property from the event before you pass it through the JavaScript bridge. Removing this property is necessary because it contains an HTML element, which cannot be stringified. Any use of the user_defined response type to write new views into the web chat must be written in HTML and JavaScript and handled inside the WebView. (For more information about the customResponse event, see the [Web chat API reference](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventscustomresponse).)
1. From the WhatsApp with Twilio integration setup page, click the Click to chat tab.
2. In the Pre-filled message field, add text that you want WhatsApp to send to your assistant on the customer's behalf to get the conversation started.

Specify a message that you know your assistant can answer in a useful way.
3. Copy the Embed link and add it to your web page. Consider adding text in front of the icon that explains what the icon does. For example, you might add a <span> HTML tag in front of the icon's <span> element that says Have a question? Ask Watson Assistant for help.

When a user clicks the icon on your web page, it opens a WhatsApp messaging session that is connected to your assistant, and adds the text you specify into the user's text field, ready to be submitted.







 Action considerations 

For the best customer experience, design your actions with the capabilities of the WhatsApp integration in mind:



* A text response that contains more than 1,600 characters is broken up into multiple responses.
* Do not include HTML elements in your text responses.
* The WhatsApp with Twilio integration does not support chat transfers that are initiated with the Connect to agent response type.
* If you use Markdown syntax, see the Supported Markdown syntax table.
* To include a hypertext link in a text response, specify the URL directly. Do not use markdown syntax for links. For example, specify Contact us at https://www.ibm.com.





Supported Markdown syntax

 Format Syntax Example 

 Italics We're talking about _practice_. We're talking about practice. 
 Bold There's no crying in baseball. There's no crying in baseball.
* For information about CSS helper classes that you can use to change the home screen style, see the [prebuilt templates](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-renderhtml) documentation.







 Showing more suggestions 

Suggestions give your customers a way to try something else when the current exchange with the assistant isn't delivering what they expect. A question mark icon ![Question mark icon](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/question-mark.png) is displayed in the web chat that customers can click at any time to see other topics that might be of interest or, if configured, to request support. Customers can click a suggested topic to submit it as input or click the X icon to close the suggestions list.

Starting with web chat version 3.1, if customers select a suggestion and the response is not helpful, they can open the suggestions list again to try a different suggestion. The input generated by the first choice is submitted and recorded as part of the conversation. However, any contextual information that is generated by the initial suggestion is reset when the subsequent suggestion is submitted.

The suggestions are shown automatically in situations where the customer might otherwise become frustrated. For example, if a customer uses different wording to ask the same question multiple times in succession, and the same dialog node is triggered each time, then related topic suggestions are shown in addition to the triggered node's response. The suggestions that are offered give the customer a quick way to get the conversation back on track.

The suggestions list is populated with dialog nodes that condition on intents that are related in some way to the matched intent. The intents are ones that the AI model considered to be possible alternatives, but that didn't meet the high confidence threshold that is required for a node to be listed as a disambiguation option. Any dialog node with a node name (or external node name) can be shown as a suggestion, unless its Show node name setting is set to Off.