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



 Testing your assistant 

Use the assistant preview to test your assistant.

The assistant preview renders your assistant as a web chat embedded in a preview web page. You can test the skills that you added to the assistant by entering text into the chat window. You can copy and paste the web page URL into a web browser and share the page with others to enlist help in testing and getting feedback about the assistant.

Unlike when you test a skill using the "Try it out" pane, any API calls that result from your interactions with the assistant hosted by the assistant preview might incur charges.



 Using the assistant preview to test your assistant 

To test the assistant from a web-hosted chat widget, complete the following steps:



1. From the Assistants page, click to open the assistant tile that you want to test.
2. Click Preview.

![Preview button](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/preview-button.png)

![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png) For environments where private endpoints are in use, keep in mind that the preview sends traffic over the internet. For more information, see [Private network endpoints](https://cloud.ibm.com/docs/assistant?topic=assistant-securitysecurity-private-endpoints).
3. In the "Assistant preview" pane, submit test utterances to see how the assistant responds.

If the Connect to agent response is displayed, it means you do not have a conversational skill added to your assistant.
Extensions are not required for an assistant, but they are recommended.



When you add a channel to your assistant, at least two instances of the channel are created. One instance of the channel is connected to the draft environment and the other instance is connected to the live environment. If you are using [multiple environments](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-multiple-environments), instances of the channel are added to your extra environments. To connect your assistant to a new channel, go to the Integrations catalog. For more information about adding integrations to your assistant, see [Adding integrations](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-integration-add).

Although a channel always exists in environments, you can configure your integration separately in each environment. For example, this allows you to test integrations on your draft environment before you go live with any integration configuration. After you add an integration, you must set it up to use it with your assistant. The Finish setup icon appears on any integration that you added but didn't yet set up.

You have multiple options for deploying your assistant, depending on how you want your customers to interact with it. In most cases, an assistant is deployed by using one of the following integrations:



* [Web chat integration](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-web-chat): The web chat integration provides a secure and highly customizable widget you can add to your website. You can configure how and where the web chat widget appears, and you can use theming to align it with your branding and website design. If a customer needs help from a person, the web chat integration can transfer the conversation to an agent.
* [Phone integration](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone): The phone integration enables your assistant to converse with customers on the phone by using the IBM Watson Text to Speech and Speech to Text services.
Note that Twilio does not support SIPS URIs, but does support secure SIP trunking by appending ;secure=true to the SIP URI.



6. Click Save.
7. Click Deploy All.







 Redirecting to the incoming call handler 

In this section you will use a TwiML Redirect** widget in your Studio Flow editor to call out to the /call-recieve function created in the previous section.



1. Add a TwiML Redirect widget to your Studio Flow canvas.
2. Connect the Incoming Call trigger to your TwiML Redirect widget.
3. Configure the TwiML Redirect widget with the URL for the /receive-call function you created in the previous section.
4. Your flow should now redirect to Watson Assistant when receiving an inbound call.
5. If the redirect fails, make sure you deployed your /receive-call function.







 Creating a Twilio function to handle transfers from assistant 

We also need to configure the call flow to handle calls being transferred from the assistant back to Twilio Flex, for cases when when customers ask to speak to an agent. To show this, we will use a Say/Play after the TwiML Redirect widget to show that the call is transferred back to the flow from Watson Assistant. Note that there are many things like queuing the call for a live agent that can happen at this point. These will be discussed below.



1. Add a new Say/Play widget to your canvas and configure it with a phrase like Transfer from Watsom complete.
2. 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.
The correct answer is returned and it includes a link to the source documentation page.

Zoom

![Shows a preview of the assistant where the test question is answered](https://cloud.ibm.com/docs-content/v1/content/f16b1f78a92498247223b337bd9303c2758b9ba8/discovery-data/images/tut-convo-test-3a.png)

Figure 34. Web chat returns search response



Congratulations! You successfully created an assistant that can answer questions about economic topics by retrieving information from working papers that are available from the US Federal Research Economic Data website.



 Summary 

In this tutorial, you created a Watson Discovery Conversational Search project with a web crawl connector that collects information about working papers from the US Federal Reserve Economic Data website. Separately, you created a Watson Assistant virtual assistant with a single action that can recognize user questions about economic subjects. You added a Search extension to your assistant that connects the action's search response to the Discovery project where economic data is stored. Finally, you tested your virtual assistant by asking a question and getting a useful response that featured data from relevant economic research papers.





 Next steps 

The assistant that you created and connected to a search extension is available from the Draft environment. Next, you can publish your assistant to a production environment and deploy it. There are a variety of methods you can use to deploy the assistant. For more information, see [Overview: Previewing and publishing](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-publish-overview).
Tutorial: Rendering a custom response as a content carousel 

This tutorial shows how you might use custom responses to render information in the form of a content carousel.

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

A content carousel (or slider) is a type of interactive element that shows options as a scrollable series of slides.

Watson Assistant does not have a built-in response type for content carousels. Instead, you can use the user_defined response type to send a custom response with the information you want to show, and extend the web chat to render the content carousel using standard JavaScript libraries.

![Content carousel in web chat](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/web-chat-tutorial-content-carousel.png)

This example shows how you can use the [Swiper](https://swiperjs.com/) library to render a custom response as a content carousel.



1. In the action step that you want to create a content carousel, use the JSON editor to define a user_defined custom response, which can contain any data you want to include. Inside the response, specify the data required for populating the content carousel. In this example, we're sending information about various types of credit cards, which we will display in a custom response:

{
"generic": [
{
"user_defined": {
"carousel_data":
{
"alt": "everyday card",
"url": "lendyr-everyday-card.jpg",
"title": "The Everyday Card",
"description": "$300 bonus plus 5% gas station cash back offer. Earn 2% cash back on all other purchases."
},
{
To change to a different language, use the [updateLanguagePack()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsupdatelanguagepack) instance method to replace the current language pack with one of the available translated language packs. For more information, see [Supporting global audiences](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-develop-global).





 Opening, closing, and rendering the web chat window 

Replacing the default launcher
: To better integrate with your website, you might want to replace the built-in launcher icon with a different mechanism for opening the web chat. To hide the default launcher, set the [showLauncher](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationoptionsshowLauncher) configuration option to false. To open the web chat based on some other interaction, use the [openWindow](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodsopenwindow) instance method.

![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
Note that Twilio does not support SIPS URIs, but does support secure SIP trunking by appending ;secure=true to the SIP URI.



6. Click Save.
7. Click Deploy All.







 Redirecting to the incoming call handler 

In this section you will use a TwiML Redirect** widget in your Studio Flow editor to call out to the /receive-call function created in the previous section.



1. Add a TwiML Redirect widget to your Studio Flow canvas.
2. Connect the Incoming Call trigger to your TwiML Redirect widget.
3. Configure the TwiML Redirect widget with the URL for the /receive-call function you created in the previous section.
4. Your flow should now redirect to Watson Assistant when receiving an inbound call.
5. If the redirect fails, make sure you deployed your /receive-call function.







 Creating a Twilio function to handle transfers from assistant 

We also need to configure the call flow to handle calls being transferred from the assistant back to Twilio Flex, for cases when when customers ask to speak to an agent. To show this, we will use a Say/Play after the TwiML Redirect widget to show that the call is transferred back to the flow from Watson Assistant. Note that there are many things like queuing the call for a live agent that can happen at this point. These will be discussed below.



1. Add a new Say/Play widget to your canvas and configure it with a phrase like Transfer from Watsom complete.
2. 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.
"type": "send",
"parameters": {
"digits":
{
"code": "9",
"volume": -8
},
{
"code": "11"
}
],
"send_interval": 100
}
},
"channels":
{
"channel": "voice_telephony"
}
]
}
]
}
}
Show more







 Transferring the conversation to the web chat integration 

You can transfer the caller from the current phone call to a [web chat](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chat) session by using the channel_transfer response type. The assistant sends an SMS message to the caller that includes a URL that the caller can tap to load the web chat widget in the phone's browser. The web chat session displays the history of the phone call and can start the process of collecting information needed to complete the transaction. This can be useful in situations where the customer can provide information more easily in writing than by speaking (for example, changing an address).

After the transfer has successfully completed, the caller can hang up the phone and continue the copnversation using the web chat. The channel_transfer response type can be used with the phone integration only if the SMS with Twilio integration is also configured for the assistant.

{
"output": {
"generic": [
{
"response_type": "text",
"values":
{
"text": "I will send you a text message now with a link to our website."
}
],
"selection_policy": "sequential"
},
{
"response_type": "channel_transfer",
"message_to_user": "Click the link to connect with an agent using our website.",
"transfer_info": {
"target": {
"chat": {
: The service now offers a WebSocket interface for synthesizing text to speech. The interface offers the same features as the /v1/synthesize method of the HTTP interface. It accepts plain text or text that is marked up with SSML. In addition, it also supports use of the SSML <mark> element to identify the time in the audio at which it finishes synthesizing all text that precedes the mark. For more information, see [The WebSocket interface](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-usingWebSocket).

Expanded language support for SSML
: The service now offers support for text that is annotated with SSML for the languages Castilian and North American Spanish, Italian, and Brazilian Portuguese. The service already supported the use of SSML for US and UK English, French, and German. As of this update, the service supports SSML for all languages but Japanese. Moreover, you can use both IBM SPR and IPA notations to define word pronunciations with the SSML <phoneme> element. For more information, see [Understanding SSML](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-ssml) and [Understanding phonetic symbols](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-symbols).

For US English, you can also use the SSML <phoneme> element to create word entries in a custom model; customization is supported only for US English. For more information, see [Understanding customization](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customIntro).

Voices updated for improved speech synthesis
: The service features improved expressiveness and naturalness for the most frequently used voices. The improvements are based on Recursive Neural Network (RNN)-based prosody prediction from input text. They are made available as a new service engine and voice-model updates for the following languages:



* en-US_AllisonVoice
Contact us at[ibm.com](https://www.ibm.com).

Remember, you must use the appropriate type of syntax in your responses for the client application to which you will deploy the conversation. Only use HTML syntax if your client application can interpret it properly. Other integration channels might expect other formats.

Deployment changes
: The Test in Slack option was removed.





 11 May 2018 

Information security
: The documentation includes some new details about data privacy. Read more in [Information security](https://cloud.ibm.com/docs/assistant?topic=assistant-information-security).





 7 May 2018 

Sydney, Australia data center opens
: You can now create Watson Assistant service instances that are hosted in the Sydney, Australia data center. See [IBM Cloud global data centers](https://www.ibm.com/cloud/data-centers/) for more details.





 4 April 2018 

Search dialogs
: You can now [search dialog nodes](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-tasksdialog-tasks-search) for a given word or phrase.





 15 March 2018 

Introducing IBM Watson® Assistant
: IBM Watson® Conversation has been renamed. It is now called IBM Watson® Assistant. The name change reflects the fact that Watson Assistant is expanding to provide prebuilt content and tools that help you more easily share the virtual assistants you build. Read [this blog post](https://www.ibm.com/blogs/watson/2018/03/the-future-of-watson-conversation-watson-assistant/) for more details.

New REST APIs and SDKs are available for Watson Assistant
: The new APIs are functionally identical to the existing Conversation APIs, which continue to be supported. For more information about the Watson Assistant APIs, see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v1).

Dialog enhancements
: The following features were added to the dialog tool:



* Simple variable name and value fields are now available that you can use to add context variables or update context variable values.
Any action can be shown as a suggestion, unless its Ask clarifying question setting is set to Off. For more information about the Ask clarifying question setting, see [Asking clarifying questions](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-understand-questionsunderstand-questions-ask-clarifying-question).

To configure suggestions, complete the following steps:



1. Open the Suggestions tab.

Suggestions are enabled automatically for new web chat integrations. If you don't want to use suggestions, toggle the switch to Off.
2. In the Include a connection to support section, specify when you want an option to connect with support to be included in the list of suggestions. You can specify Always, Never, or After one failed attempt.

After one failed attempt: Adds the option to the list only if the customer reached a node with an anything_else condition in the previous conversation turn or reaches the same action for a second time in succession.
3. In the Option label field, type the text of the message that requests help from support. This message is shown as the label for the support option, which is included in the Suggestions window under the circumstances you specified in the previous step. If the customer clicks this option, the same message is sent to the assistant.

The message you specify should trigger an action that gives customers a way to connect with support. By default, the message Connect with agent is used. If your web chat is integrated with a contact center platform, this message initiates a transfer to a human agent. (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.
(window.watsonAssistantChatOptions.clientVersion || 'latest') +
'/WatsonAssistantChatEntry.js';
document.head.appendChild(t);});

</script>
Show more

You can reference the $ismember context variable from your dialog. For example, the following screen capture shows a dialog node that conditions on #General_Greetings. It has multiple conditioned responses. The first response checks whether the current user is a member of your rewards program by checking for the presence of the $ismember context variable. If the variable is present, the response addresses the user as a member. The next response has a more generic greeting.

![Shows multiple conditioned responses in a dialog node, one of which references the ismember context variable](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/web-chat-use-context-var.png)

If you enable security, you can encrypt the data that you pass to your dialog. For more information, see [Passing sensitive data](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-securityweb-chat-security-encrypt).

If you're using a Lite plan, remember that a session ends if there's no interaction with the user after 5 minutes. When the session ends, any contextual information that you pass or collect is reset.





 Adding user identity information 

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).
For more information, see [Configuring bidirectional languages](https://cloud.ibm.com/docs/assistant?topic=assistant-language-supportlanguage-support-configure-bidirectional).



Next, start building your conversation.

As you follow the normal steps to design a conversational flow, you teach the universal language model about the language you want your skill to support. It is by adding training data that is written in the target language that the universal model is constructed. For an actions skill, add actions. For a dialog skill, add intents, intent user examples, and entities. The universal language model adapts to understand and support your language of choice.





 Integration considerations 

When your skill is ready, you can add it to an assistant and deploy it. Keep these tips in mind:



* Phone integration: If you want to deploy an assistant that uses the universal language model with the phone integration, you must connect to custom Speech service language models that can understand the language you're using. For more information about supported language models, see the [Speech to Text](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-modelsmodelsList) and [Text to Speech](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-voiceslanguageVoices) documentation.
* Search skill: If you build an assistant that specializes in a single language, be sure to connect it to data collections that are written in that language. For more information about the languages that are supported by Discovery, see [Language support](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-language-support).
* Web chat: Web chat has some hardcoded strings that you can customize to reflect your target language. For more information, see [Global audience support](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-basicsweb-chat-basics-global).