vania-janet/multiturn-rag-retrieval-data huggingface dataset:
// 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",
// A UUID like '6435434b-b3e1-4f70-8eff-7149d43d938b' included in the embed code provided in Watson Assistant.
serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
// The callback function that is called after the widget instance has been created.
onLoad: function(instance) {
instance.render();
},
showLauncher: false, // Hide the web chat launcher, you will open the WebView from your mobile application
openChatByDefault: true, // When the web chat WebView is opened, the web chat will already be open and ready to go.
hideCloseButton: true // And the web chat will not show a close button, instead relying on the controls to close the WebView
};
setTimeout(function(){const t=document.createElement('script');t.src="https://web-chat.global.assistant.watson.appdomain.cloud/versions/" + (window.watsonAssistantChatOptions.clientVersion || 'latest') + "/WatsonAssistantChatEntry.js";document.head.appendChild(t);});
</script>
</body>
</html>
Show more

In your app, make sure you include logic to hide your web chat launching mechanism when the device is offline. If the device goes offline in the middle of a conversation, appropriate error messages and retries occur.





 Using a JavaScript bridge
* Window open events: The window:pre:open and window:open events now fire any time the chat window is opened, regardless of the reason. In previous releases, these events only fired if the window was opened by the customer clicking on the built-in launcher. Other methods of opening the chat window, such as session history or custom launchers, did not fire these events.

The event data passed to the listener has a new reason property that indicates the reason the window was opened. If you want to preserve the previous behavior, you can modify your handler to check this property:

instance.on({ type: "window:open", handler: event => {
if (event.data.reason === 'default_launcher') {
// Previous code.
}
}});

For more information, see [Window open reasons](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventswindowopenreasons).
* hideCloseButton property renamed: The hideCloseButton property for custom panels has been renamed hideBackButton. The behavior of the property has not changed. For more information, see [customPanel.open()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodscustompanelopen).







 5.1.2 

Release date: 11 December 2021



* Bug fix for Salesforce integration.







 5.1.1 

Release date: 5 November 2021



* "User is typing" support: The web chat now supports displaying the "user is typing" message for service desks. This feature is supported for the Salesforce and Zendesk integrations, as well as any [starter kit](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter) integration that implements it.
* Bug fixes.







 5.1.0 

Release date: 28 October 2021
For more information, see [Showing more suggestions](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-alternate).
* Search result format change: To support the ability to show more than 3 search results in a response, the search skill response type format changed. If you are using pre:receive or receive handlers to process search results, you might need to update your code. The results property was replaced by the primary_results and additional_results properties. For more information about the new search skill response type format, see the [API reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2message).
* Language pack key change: Due to improvements that were made to allow you to specify separate chat transfer messages for situations where agents are available and unavailable, the [language source file](https://github.com/watson-developer-cloud/assistant-web-chat/tree/master/languages) was updated. The agent_chatDescription was renamed to default_agent_availableMessage and another key (default_agent_unavailableMessage) was added. If you defined a custom string for the agent_chatDescription key, you must modify your code to reflect this change. For more information about the new availability messages and how they are used, see [Adding a Connect to human agent response type](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-connect-to-human-agent).







 2.4.0 

Release date: 2 September 2020



* 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
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.

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.
Tutorial: implementing custom option buttons in the web chat 

This tutorial shows how you might replace the default rendering of an options response with your own custom clickable buttons.

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

By default, the web chat always displays an options response as a set of clickable buttons (for 4 or fewer options) or as a drop-down list (for 5 or more more options). This example shows the default rendering of an options response with 3 options:

![Options response rendered as 3 buttons](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-tutorial-custom-buttons-1.png)

For this tutorial, we will replace this default rendering with larger, card-style buttons:

![Options response rendered as 3 custom card-style buttons](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-tutorial-custom-buttons-2.png)

Because the rendering of an options response cannot be modified, we will do this by intercepting any incoming options responses from the assistant and converting them into custom (user_defined) responses. We can then implement a custom rendering for these responses.



1. Create a handler for the [pre:receive](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventsprereceive) event. In this handler, look for any option responses in the message payload, and convert them into user_defined responses.

function preReceiveHandler(event) {
N 



The URL specified by the source property can be either of the following:



* The URL of an audio file in any standard format such as MP3 or WAV. In the web chat, the linked audio clip will render as an embedded audio player.
* The URL of an audio clip on a supported streaming service. In the web chat, the linked audio clip will render using the embeddable player for the hosting service.

Specify the URL you would use to access the audio file in yourbrowser (for example, https://soundcloud.com/ibmresearchfallen-star-amped). You do not need to convert the URL to anembeddable form; the web chat will do this automatically.

You can embed audio hosted on the following services:



* [SoundCloud](https://soundcloud.com)
* [Mixcloud](https://mixcloud.com)





For the phone integration, the URL must specify an audio file that is single-channel (mono) and PCM-encoded, and is sampled at 8,000 Hz with 16 bits per sample.





 Example 

This example plays an audio clip with a title and descriptive text.

{
"generic":[
{
"response_type": "audio",
"source": "https://example.com/audio/example-file.mp3",
"title": "Example audio file",
"description": "An example audio clip returned as part of a multimedia response."
}
]
}







 channel_transfer 

Requests that the conversation be transferred to a different channel integration. Currently, the web chat integration is the only supported target of a channel transfer.



 Integration channel support 



 Phone SMS Slack Facebook WhatsApp 

 ![Yes](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/checkmark-icon.svg) !
Managing user identity information 

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

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.

If 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. Choose a non-human-identifiable ID. For example, do not use a person's email address as the user ID.

In addition, 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. (For more information about deleting user data, see [Labeling and deleting data](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-admin-securingsecuring-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.

If you enable security, you set the user ID in the JSON Web Token instead.
* The embed script that contains your integration ID, region, service instance ID, and subscription ID (if applicable) needs be changed or updated to use the IDs for the new integration and region.
* If you are using Salesforce or ZenDesk integrations for connecting to human agents, update the configuration within those systems to make sure they can communicate with the correct integration. Follow the instructions on the Live agent tab in the web chat configuration for setting up those systems. This is only needed for obtaining the conversation history for the agent.
* If you have web chat security enabled and you are using encrypted payloads, the IBM-provided public key used for the encryption may be different depending on region. If so, you need to update the system that generates the JSON Web Token (JWT) to use the correct key.



You can set up an active/active configuration of web chat by using different integration IDs in your embed scripts, and by ensuring the web chat integration is "sticky" by user. Otherwise, if the user fails over to a different integration, the conversation history might be lost.







 API 



 Monitoring 

Capture and monitor response codes of /message calls. Response codes of live /message traffic should be captured and aggregated.

Ideally, save the response code statistics in an external persistence store. This shared store can aggregate response code results from all deployed instances of a your application and provide the greatest fidelity in determining if a failover should be triggered.

Alternatively, response codes can be aggregated and evaluated in memory for a given instance of your application. As only a fraction of traffic is contributing to the failover decision, this could lead to different behavior with respect to how often the failover decision is acted upon.

With either aggregation approach, exceeding a defined threshold could trigger a failover. Common approaches for determining a failover include:



* Percentage-based: greater than X% of requests return a non-200 response code
* Consecutive-based: X calls in a row return a non-200 response code
* Limit-based: X calls return a non-200 response in a given timeframe



To avoid an unnecessary failover between regions, make sure a robust retry mechanism is present when calling the /message endpoint.





 Failover for v1 and v2 stateless API
For more information, see [Starting and ending the dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-start).





 15 January 2021 

Use new webhooks to process messages!
: A set of new webhooks is available as a beta feature. You can use the webhooks to perform preprocessing tasks on incoming messages and postprocessing tasks on the corresponding responses. You can use the new log webhook to log each message with an external service. For more information, see [Webhook overview](https://cloud.ibm.com/docs/assistant?topic=assistant-webhook-overview).

New service desk support reference implementation
: You can use the reference implementation details to integrate the web chat with the NICE inContact service desk. For more information, see [Adding service desk support](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-haa).

Phone and SMS with Twilio integration updates
: The phone integration now enables you to specify more than one phone number, and the numbers can be imported from a comma-separated values (CSV) file. The SMS with Twilio integration no longer requires you to add your SMS phone number to the setup page.





 6 January 2021 

Import and export UI changes
: The label on buttons for importing intents and entities changed from Import to Upload. The label on buttons for exporting intents and entities changed from Export to Download.





 4 January 2021 

Dialog methods updates
: Documentation and examples were added for the following supported dialog methods:



* JSONArray.addAll(JSONArray)
* JSONArray.containsIgnoreCase(value)
* String.equals(String)
* String.equalsIgnoreCase(String)



For more information, see [Expression language methods](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-methods).





 17 December 2020 

Accessibility improvements
: The product was updated to provide enhanced accessibility features.
For example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:80.0) Gecko/20100101 Firefox/80.0
* client_ip_address: IP address of the customer's computer. For example: 183.49.92.42





 Example: Using page URL information in your dialog 

You might embed the web chat in multiple pages on your website. Let's say you want to route chat transfers from the web chat to different Salesforce agents based on the page from which the customer asks to speak to someone. If the customer is on the insurance plans page of your website (https://www.example.com/insurance.html), you want to route them to agents who are experts in your company's insurance plans. If the customer is on the investments web page (https://www.example.com/invest.html), you want to route them to agents who are experts in your company's investment opportunities. You can add multiple conditioned responses to the dialog node where the transfer takes place and add logic like this:



 Conditioned response 1 



* Condition: $integrations.chat.browser_info.page_url.contains('insurance.html')
* Response type: Connect to human agent
* Button ID: Z23453e25vv (The button that routes to the insurance experts agent queue)







 Conditioned response 2 



* Condition: $integrations.chat.browser_info.page_url.contains('invest.html')
* Response type: Connect to human agent
* Button ID: Z23453j24ty (The button that routes to the investment experts agent queue)



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).
Unlike when you send test utterances to your assistant from the "Try it out" pane, standard usage charges apply to API calls that result from utterances that are submited to the chat widget.







 Next steps 

Now that you have built and tested your dialog skill, you can share it with customers. Deploy your skill by first connecting it to an assistant, and then deploying the assistant. There are several ways you can do this. See [Adding integrations](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-integration-add) for more details.
* A [chat deployment](https://help.salesforce.com/articleView?id=live_agent_create_deployments.htm&type=5).
* A [chat button deployment](https://help.salesforce.com/articleView?id=live_agent_create_buttons.htm&type=5).
* Routing must be configured for the chat button. See [Chat routing options](https://help.salesforce.com/articleView?id=live_agent_chat_routing_options.htm&type=5).
* If you choose omni-channel routing, be sure to include omni-channel as a utility in the chat app. See [Omni-Channel](https://help.salesforce.com/articleView?id=omnichannel_intro.htm&type=5).



You must have a level of access to your Salesforce service desk deployment that allows you to do the following things:



* Edit the chat app
* Get chat deployment and button code details
* Add custom fields to layout objects
* Create Visualforce pages



If you don't, ask someone with the appropriate level of access to perform this procedure for you.





 Setting up the Salesforce service desk connection 

To set up a Salesforce service desk integration, complete the following steps:



1. Go to your web chat settings. For more information, see [Integrating the web chat with your website](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat).
2. From the web chat integration page in Watson Assistant, set the Allow transfers to live agents switch to On, and then choose Salesforce as the service desk type. Click Next.
3. For Watson Assistant to connect to a Salesforce service desk, it needs information about your organization's Salesforce chat deployment and button implementations. Specifically, it needs the API endpoint, organization ID, deployment ID, and button ID. The service can derive the values that it needs from code snippets that you copy and paste to this configuration page.
* Customize the CSS theme: For more information, see [Theming](https://integrations.us-south.assistant.watson.cloud.ibm.com/web/developer-documentation/api-instance-methodstheming).
* Shadow DOM is no longer used: When you use custom response types or HTML in your dialog, you can apply CSS styles that are defined in your web page to the assistant's response. To override any default styling in the web chat, you must specify the !important modifier in your CSS. For more information, see [Rendering response types](https://integrations.us-south.assistant.watson.cloud.ibm.com/web/developer-documentation/api-renderhtml).
Adding custom dialog flows for integrations 

Use the JSON editor in dialog to access information that is submitted from the web chat integration.

The context object that is passed as part of the v2 /message API request contains an integrations object. This object makes it possible to pass information that is specific to a single integration type in the context. For more information about context variables, see [Context variables](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-runtime-contextdialog-runtime-context-variables).

The integrations object is available from the v2 API in version 2020-04-01 or later only.



 Web chat: Accessing sensitive data 

If you enable security for the web chat, you can configure your web chat implementation to send encrypted data to the dialog. Payload data that is sent from web chat is stored in a private context variable named context.integrations.chat.private.user_payload. No private variables are sent from the dialog to any integrations. For more information about how to pass data, see [Passing sensitive data](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-chatdeploy-web-chat-security-encrypt).

To access the payload data, you can reference the context.integrations.chat.private.user_payload object from the dialog node condition.

You must know the structure of the JSON object that is sent in the payload.

For example, if you passed the value "mvp:true" in the JSON payload, you can add a dialog flow that checks for this value to define a response that is meant for VIP customers only. Add a dialog node with a condition like this:



Private variable as node condition

 Field Value 

 If assistant recognizes $integrations.chat.private.user_payload.mvp 
 Assistant responds I can help you reserve box seats at the upcoming conference! 







 Web chat: Accessing web browser information 

When you use the web chat integration, information about the web browser that your customer is using to access the web chat is automatically collected and stored.