vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Tutorial: Customizing text elements based on the current page 

This tutorial shows how you can dynamically customize the launcher or home screen text based on the page the user is currently viewing.

For a complete, working version of the example described in this tutorial, see [Change launcher and home screen text for Watson Assistant web chat](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/change-launcher-and-home-screen-text).

The launcher text and home screen greet the user and suggest what the user might want to do. Rather than showing the same text all the time, you might want to customize this text based on the page on your website the user is currently viewing. For example, instead of a generic greeting, a customer viewing a page about credit cards might see text that is specific to credit card services.

Although this example shows how to adapt the text based on the current page, you can use the same basic approach to adapt the text based on any client condition (such as the time of day or the user's geographical location).

To change the launcher or home screen text elements based on the current page the user is viewing, follow these steps:



1. Determine what page the user is currently viewing. Depending on the design of your application, there are various ways to do this, but one simple mechanism is to check the value of a URL query parameter (in this example, page):

const page = new URLSearchParams(window.location.search).get('page');
2. When the web chat is loaded, check this value and conditionally set the text based on which page is being viewed. You can use any condition that makes sense for your application. In this example, we are simply checking the value of the page query parameter:

if (page === 'cards') {
// Update the launcher and home screen with text that is
// specific to credit cards.
...
} else if (page === 'account') {
// Update the launcher and home screen with text that is
// specific to the user's account.
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 

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:

![An example of the initial launcher](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/web-chat-icon.png)

After 15 seconds, the launcher expands to show a greeting message to the user. In this expanded state, a customer can still click the launcher to open the web chat. (If the customer reloads the page or navigates to a different page before the launcher has expanded, the 15-second timer restarts.) There are two slightly different appearances for this expanded state, depending on whether the user is using a desktop browser or a mobile browser.



* For desktop browsers, the expanded launcher shows two primary buttons the customer can click to open the web chat, and a Close button that closes the launcher:

![An example of the desktop launcher](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/desktop-launcher.png)

The expanded launcher remains in its expanded state even if the customer reloads the page or navigates to a different page.
(For more information about integrating with a contact center, see [Adding contact center support](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat-haa).)

If your web chat is not integrated with a contact center, specify a message that helps your customers reach whatever form of support you do offer. If you offer a toll-free support line, you might add Get the support line phone number. Or if you offer an online support request form, you might add Open a support ticket.

Whether you use the default support message or add your own, make sure your action is designed to recognize the message and respond to it appropriately.
* [SMS](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-sms)
* [WhatsApp with Twilio](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-whatsapp)
* [Search](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-search-add)



You can also set up live agent integrations by going to the Live agent tab from the Web chat tile. The options include:

Web chat live agent integrations



* [Web chat with Salesforce support](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-salesforce)
* [Web chat with Zendesk support](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-zendesk)



Web chat live agent reference implementations



* [Genesys Cloud](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/genesys/webChat)
* [NICE inContact](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/incontact/webChat)
* [Twilio Flex](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/flex/webChat)
* [Kustomer](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/kustomer/webChat)
* [Bring your own (starter kit)](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter)



Phone live agent integrations
For more information, see [Configuring the home screen](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-configure-home-screen).

Suggestions
: You can configure how and when the web chat offers offers suggestions to customers when the assistant isn't delivering what they expect. For more information, see [Configuring suggestions](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-suggestions).

Security
: You can protect your users' private information and prevent unauthorized messages to your assistant by enabling security on the Security tab. For more information about web chat security and how it works, see [Security](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-architecture-security).
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.

Two new history events, [history:begin](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventshistorybegin) and [history:end](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventshistoryend) announce the beginning and end of the history of a reloaded session. These events can be used to view the messages that are being reloaded. The history:begin event allows you to edit the messages before they are displayed.
[development icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/development-icon.png)Tutorial: For a tutorial showing how to render a custom response type as a replacement for the default options response, see [Tutorial: implementing custom option buttons in the web chat](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-develop-custom-buttons).

Implementing a contact center integration
: You can use one of the web chat starter kits to integrate with a contact center (service desk) platform other than the ones available in as built-in Watson Assistant integrations. Fully functional reference implementations are available for several contact center platforms; in addition, you can use a starter kit to develop a custom integration with the platform of your choice.

For more information, see [Adding contact center support](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat-haa).





 Managing data 

Managing user identity information
: The web chat associates a user ID with each message it sends to the assistant; this user ID is used for user-based billing and other purposes. You can either allow the web chat to generate an anonymous ID for each user, or you can control the user ID yourself.

Depending on whether you have enabled security for the web chat, you can use either the [updateUserID](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdateuserid) instance method or the [updateIdentityToken](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdateidentity) method to specify user identity information.
You can add a message to show when agents are available and a message to show when agents are unavailable. Each message can be up to 320 characters in length.

Web chat built-in service desk integrations only: The text you add to the Response when agents are online and Response when no agents are online fields is used for transfers in web chat version 3 and later. If you don't add your own messages, the hint text (the grayed out text that is displayed as the example messages) is used.

If you use this response type in multiple nodes and want to use the same custom text each time, but don't want to have to edit each node individually, you can change the default text that is used by the web chat. To change the default messages, edit the [language source file](https://github.com/watson-developer-cloud/assistant-web-chat/tree/master/languages). Look for the default_agent_availableMessage and default_agent_unavailableMessage values. For more information about how to change web chat text, see [Languages](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodslanguages).
4. Optional: If the channel where you deploy the assistant is integrated with a service desk, you can add initial routing information to pass with the transfer request.



* Pick the integration type from the Service desk routing field.
* Add routing information that is meaningful to the service desk you are using.



Service desk routing options

 Service desk type Routing information Description 

 Salesforce Button ID Specify a valid button ID from your Salesforce deployment. For more information, see [Adding routing logic for Salesforce transfers](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-salesforcedeploy-salesforce-routing). 
 Zendesk Department Specify a valid department name from your Zendesk account. For more information, see [Adding routing logic for Zendesk transfers](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-zendeskdeploy-zendesk-routing).
* Secondary color: The color of the user input message bubble.
* Accent color: The color of interactive elements, including:



* Chat launcher button that is embedded in your web page
* Send button associated with the input text field
* Input text field border when in focus
* Marker that shows the start of the assistant’s response
* Border of a button after it is clicked
* Border of the drop-down list field as the user chooses an option
* Typing indicator that is shown to repesent a pause response





Style changes you make are immediately applied to the preview that is shown on the page, so you can see how your choices impact the style of the chat UI.



* IBM Watermark: Enables or disables the Built with IBM Watson watermark displayed in the web chat window. The watermark is always enabled for any new web chat integrations on Lite plans.



6. If you want to add an image that represents your assistant or organization to the web chat header, click Add an avatar image.

Specify the URL for a publicly accessible hosted image, such as a company or brand logo or an assistant avatar. The image file must be between 64 x 64 and 100 x 100 pixels in size.

Click Save.
7. Configure the home screen for the chat window.

The home screen helps to ease your customers into a conversation with your assistant. You can add a greeting and a list of quick conversation starter questions for customers to click. For more information, see [Configuring the home screen](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-home-screen).

If you don't want to use a home screen, go to the Home screen tab and toggle the switch to Off.
8. Optional: To configure support for transferring conversations to a service desk agent, click the Live agent tab. For more information, see [Adding service desk support](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-haa).
9.
(This class is also defined in the [full example](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/custom-buttons).)

function onClick(messageItem, button, fullMessage, itemIndex) {
webChatInstance.send({ input: { text: messageItem.label }});
button.classList.add('CardButton--selected');
}
5. If the user reloads the page or navigates to a different page, the web chat reloads from the session history. If this happens, we want to preserve the "selected" state of any clicked buttons.

To do this, in the onClick handler, use the [updateHistoryUserDefined](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdateHistoryUserDefined) instance method to store a variable in the session history that indicates which button was clicked.

webChatInstance.updateHistoryUserDefined(fullMessage.id, { selectedIndex: itemIndex });

Then, in the customResponse handler, read this value and use it to set the initial states of the buttons in any custom responses already in the session history.

if (fullMessage.history?.user_defined?.selectedIndex === index) {
button.classList.add('CardButton--selected');
}



For complete working code, see the [Custom buttons for Watson Assistant web chat](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/custom-buttons) example. The example also shows how to disable the buttons in a custom response after the customer has sent a message, which prevents using the buttons to send a message out of order.
* Date picker: If you configure a step to collect a Date customer response, the step now uses the new date response type to request that the web chat display a graphical date picker the customer can use to select a date, as an alternative to typing the date in the input field. Existing steps do not automatically inherit this behavior; if you want to use the date picker, you must delete the existing Date response and then re-add it.
* Skip "connect to agent" card: A new serviceDesk.skipConnectAgentCard configuration option is available. If this option is enabled, the web chat immediately connects to an agent when it receives a Connect to agent response, without first displaying a card and waiting for the user to click.
* Close button: A new showCloseAndRestartButton configuration option specifies whether the web chat interface shows an X (Close) button in addition to the existing - (Minimize) button. A customer can click this button to close the web chat, end the conversation, and end any conversation with a human agent. The chat transcript is also cleared, but any transcript of a conversation with a human agent is preserved.







 6.3.0 

Release date: 24 March 2022



* Search cards: Search cards have a new design.
* New restartConversation() method: The new restartConversation() instance method restarts the conversation with the assistant by clearing the web chat transcript and starting a new session. It also fires two new events (pre:restartConversation and restartConversation).

For more information, see [instance.restartConversation()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsrestartconversation), [pre:restartConversation](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventsprerestartconversation), and [restartConversation](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventsrestartconversation).
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).



 Securing the web chat 

Understand what you need to do to secure your web chat integration.

Configure the web chat to authenticate users and send private data from your embedded web chat.

All messages that are sent from the web chat are encrypted. When you enable security, your assistant takes an additional step to verify that messages originate from the web chat that is embedded in your website only.

The web chat uses an RSA signature with SHA-256 (RS256) to encrypt communication. RS256 signatures use a sophisticated type of RSA encryption. An RSA key pair includes a private and a public key. The RSA private key is used to generate digital signatures, and the RSA public key is used to verify digital signatures. The complexity of the RSA algorithm that is used to scramble the message makes it nearly impossible to unscramble the message without the key.

The following diagram illustrates the requests that are sent back and forth to authenticate a request.

![Shows the order in which requests are sent among your website, web chat, and the service](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/web-chat-security.png)

You can implement the following security measures:



* Ensure that messages sent from the web chat to your assistant come from your customers only
* Send private data from the web chat to your assistant





 Before you begin 

The process you use to add the web chat to your website is simple. Its simplicity also means it can be misused. That's why it's important to verify that the messages sent to your assistant are coming from authorized users only.

Before you enable security, complete the following steps:



1. Create a RS256 private/public key pair.

You can use a tool such as the OpenSSL command line or PuTTYgen.
Connect the Return node on the TwiML Redirect widget to your Say/Play widget.
3. Click the Trigger widget.
4. Copy the value from the WEBHOOK URL field. You will need this value in a subsequent step.
5. On the Twilio Functions page, click Add > Add Function to add another new function to your service. Name this new function /refer-handler.
6. Replace the template in your /refer-handler function with the following code:

exports.handler = function(context, event, callback) {
// This function handler will handle the SIP REFER back from the Watson Assistant Phone Integration.
// Before handing the call back to Twilio, it will extract the session history key from the
// User-to-User header that's part of the SIP REFER Refer-To header. This session history key
// is a string that is used to load the agent application in order to share the transcripts of the caller
// with Watson Assistant to the agent.
// See https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/blob/main/docs/AGENT_APP.md
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const STUDIO_WEBHOOK_URL = '{webhook_url}';

let studioWebhookReturnUrl = ${STUDIO_WEBHOOK_URL}?FlowEvent=return;

const response = new VoiceResponse();
console.log("ReferTransferTarget: " + event.ReferTransferTarget);

const referToSipUriHeaders = event.ReferTransferTarget.split("?")[1];
console.log(referToSipUriHeaders);
if (referToSipUriHeaders) {
const sanitizedReferToSipUriHeaders = referToSipUriHeaders.replace(">", "");
If you do not enable security, and you want to perform tasks where you need to know the user who submitted the input, then you must pass the user ID to the web chat integration.

If you do enable security, you set the user ID in the JSON Web Token instead. For more information, see [Authenticating users](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-securityweb-chat-security-authenticate).

Choose a non-human-identifiable ID. For example, do not use a person's email address as the user_id.

User information is used in the following ways:



* User-based service plans use the user_id associated with user input for billing purposes. See [User-based plans](https://cloud.ibm.com/docs/assistant?topic=assistant-admin-managing-planadmin-managing-plan-user-based).
* The ability to delete any data created by someone who requests to be forgotten requires that a customer_id be associated with the user input. When a user_id is defined, the product can reuse it to pass a customer_id parameter. See [Labeling and deleting data](https://cloud.ibm.com/docs/assistant?topic=assistant-information-securityinformation-security-gdpr-wa).

Because the user_id value that you submit is included in the customer_id value that is added to the X-Watson-Metadata header in each message request, the user_id syntax must meet the requirements for header fields as defined in [RFC 7230](https://tools.ietf.org/html/rfc7230section-3.2).



To support these user-based capabilities, add the [updateUserID() method](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdateuserid) in the code snippet before you paste it into your web page.

In the following example, the user ID L12345 is added to the script.

<script>
window.watsonAssistantChatOptions = {