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



 Making a programmatic call from dialog 

To make a programmatic call, define a webhook that sends a POST request callout to an external application that performs a programmatic function. You can then invoke the webhook from one or more dialog nodes.

A webhook is a mechanism that allows you to call out to an external program based on something happening in your program. When used in a dialog skill, a webhook is triggered when the assistant processes a node that has a webhook enabled. The webhook collects data that you specify or that you collect from the user during the conversation and save in context variables. It sends the data as part of a HTTP POST request to the URL that you specify as part of your webhook definition. The URL that receives the webhook is the listener. It performs a predefined action using the information that you pass to it as specified in the webhook definition, and can optionally return a response.

You can use a webhook to do the following types of things:



* Validate information that you collected from the user.
* Interact with an external web service to get information. For example, you might check on the expected arrival time for a flight from an air traffic service or get a forecast from a weather service.
* Send requests to an external application, such as a restaurant reservation site, to complete a simple transaction on the user's behalf.
* Trigger a SMS notification.
* Trigger a IBM Cloud® Functions web action.



You cannot use a webhook to call a Cloud Functions action that uses token-based Identity and Access Management (IAM) authentication. However, you can make a call to a secured Cloud Functions web action. For more information, see [Calling an IBM Cloud Functions web action](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-webhooksdialog-webhooks-cf-web-action).
For more information, see [Making a call before processing a message](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-webhook-pre).

For environments where private endpoints are in use, keep in mind that a webhook sends traffic over the internet.



 Defining the webhook 

You can define one webhook URL to use for processing every message response before it is sent to the channel and shown to the customer.

The programmatic call to the external service must meet these requirements:



* The call must be a POST HTTP request.
* The call must be completed in 30 seconds or less.
* The format of the request and response must be in JSON. For example: Content-Type: application/json.



Do not set up and test your webhook in a production environment where the assistant is deployed and is interacting with customers.

To add the webhook details, complete the following steps:



1. In your assistant, open the environment where you want to configure the webhook.
2. Click the ![Environment settings icon](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/gear-icon-black.png) icon to open the environment settings.
3. On the Environment settings page, click Webhooks > Post-message webhook.
4. Set the Post-message webhook switch to Enabled.
5. Decide whether to return an error if the webhook call fails.

When enabled, everything stops until the processing step is completed successfully.



* If you have a critical postprocessing step that must be taken before you want to allow the response to be sent to the customer, then enable this setting.
* When this setting is disabled, the assistant ignores any errors it encounters and continues to process the response without taking the processing step. If the postprocessing step is helpful but not critical, consider keeping this setting disabled.



6.
Integrating with a custom client app 

IBM Cloud

If the available integration channels do not meet your needs, you can build your own client application as the interface between the assistant and your customers.

For more information, see [Building a custom client using the API](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-api-client).
For this tutorial, you will create an assistant with a single action. First, you must create a Watson Assistant service instance.

Both Lite and Trial plan Watson Assistant service instances are available at no cost. You will create a Trial plan.



1. From a new web browser tab, return to the IBM Cloud catalog.

Keep the Discovery page open in a separate tab so you can switch easiily between the two applications.
2. From the [Watson Assistant](https://cloud.ibm.com/catalog/services/watson-assistant) resource page in the IBM Cloud catalog, create a Trial plan Watson Assistant service instance in the Dallas location.
3. From the Watson Assistant plan service page in IBM Cloud, click Launch Watson Assistant.

The Watson Assistant product user interface is displayed where you can create your first assistant.
4. Add Discovery expert as the assistant name, and then click Next.
5. If you are asked to share information about you and your assistant, complete the required fields, and then click Next.

When you create an assistant, a web chat application is created for you automatically.
6. 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/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/tut-neural-assistant.png)

Figure 4. Assistant home page

Before we add anything to our new assistant, let's check on the status of our data.





 Step 5: Prepare your data for retrieval 

To improve the retrievability of the information in your PDF files, you will split the PDF files into many smaller documents. To do so, you will first teach Discovery about the structure of your PDF files, so it understands how subsections are formatted and can split the document by subsection.



1. Return to the web browser tab where your Discovery project is displayed.
* Added beta support for file sharing with custom service desk integrations, which currently only includes user information strings in English. For more information, see [Custom service desks](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=service-desks-custom-sd).







 7.2.2 

Release date: 1 May 2023



* Bug fixes.







 7.2.1 

Release date: 24 April 2023



* Bug fixes.







 7.2.0 

Release date: 10 April 2023



* Added support for inline iframe responses. For more information, see [Response types reference](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-response-types-referenceiframe).
* Redesigned the agent conversation experience.
* Bug fixes.







 7.1.1 

Release date: 13 February 2023



* New journey events: The new [tour:start](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventstourstart), [tour:end](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventstourend), and [tour:step](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventstourstep) events provide details about the user's progress through a journey (also known as a tour). These events can be used to navigate to a specific page when the user starts a journey or reaches a certain step, or to show a survey after a journey ends.
* New journey instance methods: The new [tours](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodstours) object supports instance methods that provide better control over journeys. You can use these methods to start or end a journey, or to automatically navigate through a journey in response to user actions.
Emotion Analysis can detect emotions that are associated with targeted phrases, entities, or keywords, or it can analyze the overall emotional tone of your content.

Example portion of a document enriched with Emotion Analysis:

{
"text": "The stockholders were pleased that Acme Corporation plans to build a new factory in Atlanta, Georgia.",
"enriched_text": {
"emotion": {
"document": {
"emotion": {
"disgust": 0.102578,
"joy": 0.626655,
"anger": 0.02303,
"fear": 0.018884,
"sadness": 0.096802
}
}
}

In the preceding example, you could query the joy Emotion by accessing enriched_text.emotion.document.emotion.joy

Emotion Analysis analyzes your text and calculates a score for each emotion (anger, disgust, fear, joy, sadness) on a scale of 0.0 to 1.0. If the score of any emotion is 0.5 or higher, then that emotion is detected. The higher the score above 0.5, the higher the relevance. In the snippet shown, joy has a score above 0.5, so Watson detected joy.

Emotion Analysis is supported in English only.





 Element classification 

The Element Classification enrichment is deprecated and will no longer be available, effective 10 July 2020.

Parses elements (sentences, lists, tables) in governing documents to classify important types and categories For more information, see [Element classification](https://cloud.ibm.com/docs/discovery?topic=discovery-element-classification).

[Smart Document Understanding](https://cloud.ibm.com/docs/discovery?topic=discovery-sdu) is unavailable if this enrichment is used.



 Enrichment pricing 

Enrichment pricing information is available on [IBM Cloud](https://cloud.ibm.com/catalog/services/discovery).





 Enrichment language support
: If a request contains both an error in the emotion feature and a valid feature request for another feature, the response returns a 200 with a warning for the emotion feature.
: The error log has changed from emotion request must specify at least one of: document, targets to emotion request must specify at least one of: document or targets.
: Requests that include the emotion feature with any nonstring elements in the targets list returns an error.





 1 December 2021 

Tone analytics
: [Tone analytics](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) is now available, for English and French languages only. The tone analytics feature detects excited, frustrated, impolite, polite, sad, satisfied, and sympathetic tones from text.





 12 October 2021 

Keyword and syntax support for additional languages
: Support for keywords and syntax is now available, for all public and premium service instances, for the following languages: Hindi, Romanian, and Turkish. In addition, syntax is available for all supported languages. For details, see [Language support](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-language-support).





 15 August 2021 

Custom classification feature
: The [custom classifications](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-classifications) feature is now generally available (GA).

Categories stock model updated
: The [categories stock model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-categories-hierarchy) has been updated to use the [IAB Tech Lab 2.0 taxonomy](https://iabtechlab.com/standards/content-taxonomy/).





 5 May 2021 

Advanced Rules beta feature deprecated
: The advanced rules beta feature is deprecated. As of June 10, 2021, you will not be able to deploy advanced rules models to Natural Language Understanding; existing models will keep running. After June 24, 2021, no advanced rules models will run in Natural Language Understanding.





 25 March 2021 

Custom classifications beta feature
This can help you better understand your interactions with customers and improve your communications generally, or for specific customers.



 Reformatting your input data 

In Watson Tone Analyzer, you pass the /v3/tone_chat method a JSON ToneChatInput object consisting of utterances, text, and an optional user string fields. For Natural Language Understanding, you pass a JSON object that contains text to be analyzed, and a language-specific model classification ID, to the /v1/analyze method.

![Tone Analyzer request mapping to NLU](https://cloud.ibm.com/docs-content/v1/content/d378657c4d97b43519fffc87c2e159d9b5a0562f/natural-language-understanding/images/ToneAnalyzerRequest.png).





 Understanding your response content 

In Watson Tone Analyzer, the service returns a JSON UtteranceAnalyses object that contains a single field, utterances_tone, which contains an array of UtteranceAnalysis objects, including score and tone_id. For Natural Language Understanding, a classifications field is returned, containing confidence and class_name objects that correspond to the Watson Tone Analyzer score and tone_id objects.

![Tone Analyzer response mapping to NLU](https://cloud.ibm.com/docs-content/v1/content/d378657c4d97b43519fffc87c2e159d9b5a0562f/natural-language-understanding/images/ToneAnalyzerResponse.png).
Tone Analyzer 

The installable IBM Watson® Tone Analyzer service uses linguistic analysis to detect emotional and language tones in written text.

The Watson packages are deprecated. Please use the [Watson SDKs](https://cloud.ibm.com/docs/watson?topic=watson-using-sdks) to perform Watson related functionality. For more information about which Watson SDK is included in the available runtimes, see the [Functions runtime](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-runtimes) documentation.

This service can analyze tone at both the document and sentence levels. You can use the service to understand how your written communications are perceived and then to improve the tone of your communications. Businesses can use the service to learn the tone of their customers' communications and to respond to each customer, or to understand and improve their customer conversations..

Request logging is disabled for the Tone Analyzer service. The service doesn't log or retain data from requests and responses, regardless of whether the X-Watson-Learning-Opt-Out request header is set.

The Tone Analyzer package contains the following entities. You can find more details in the Tone Analyzer API reference by clicking the entity name.



Table 2. Tone analyzer package entities

 Entity Type Parameters Description 

 tone-analyzer-v3 Package username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url Work with the Tone Analyzer service. 
 tone Action username, password, iam_access_token, iam_apikey,iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, tone_input, content_type, sentences, tones, content_language, accept_language Analyze general tone. 
 tone-chat Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, utterances, content_language, accept_language Analyze customer engagement tone.
Reviewing and debugging your actions 

Learn how to test the conversation you built into an action, to experience what your users see with your assistant. If there are any issues, learn how to debug the user’s experience.



 Using Preview to test your action 

As you make changes, test the action at any time to see whether the resulting interaction works as intended. Preview, which is a button on every action page, shows you what customers see when they use web chat to interact with the action.

Before you test your action, make sure you save any new changes, and wait until the system finishes training. If the system is still training, a message is displayed that says so.



1. Click Preview. The Greet customer action starts.
2. In the chat window, type some text and then press Enter.
3. Check the response to see if your assistant correctly interpreted the input, started the intended action, and performed the appropriate step.

The Preview pane names the action that was recognized in the input.

Zoom

![Preview](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/review-preview.png)

Preview

If the assistant doesn't understand a phrase, you see the built-in action No action matches.
4. Continue to converse with your assistant to see how the conversation flows.
5. To remove prior test utterances from the chat pane and start over, click the Reset icon. Not only are the test utterances and responses removed, but this action also clears the values of any variables that were set as a result of your previous interactions.



Queries that you submit through the Preview pane generate /message API calls, but they are not logged and do not incur charges.



 Saving changes before testing 

Preview represents updates from the last time that the assistant was saved.

Changes are saved when you:



* Select the save icon
* Click a new step
* Open Preview
* Reset Preview
See [Entity extraction](https://cloud.ibm.com/docs/discovery?topic=discovery-configserviceentity-extraction) and [Keyword extraction](https://cloud.ibm.com/docs/discovery?topic=discovery-configservicekeyword-extraction) about those enrichments.

The subject, action, and object are extracted for every sentence that contains a relation.





 Sentiment analysis 

Identifies attitude, opinions, or feelings in the content that is being analyzed. Discovery can calculate overall sentiment within a document, sentiment for user-specified targets, entity-level sentiment, quotation-level sentiment, directional-sentiment, and keyword-level sentiment. The combination of these capabilities supports a variety of use cases ranging from social media monitoring to trend analysis.

Example portion of a document enriched with Sentiment Analysis:

{
"text": "The stockholders were pleased that Acme Corporation plans to build a new factory in Atlanta, Georgia.",
"enriched_text": {
"sentiment": {
"document": {
"score": 0.459813,
"label": "positive"
}
}

In the preceding example, you could query the sentiment label by accessing enriched_text.sentiment.document.label

The label is the overall sentiment of the document (positive, negative, or neutral). The sentiment label is based on the score; a score of 0.0 would indicate that the document is neutral, a positive number would indicate the document is positive, a negative number would indicate the document is negative.





 Emotion analysis 

Detects anger, disgust, fear, joy, and sadness implied in English text. Emotion Analysis can detect emotions that are associated with targeted phrases, entities, or keywords, or it can analyze the overall emotional tone of your content.

Example portion of a document enriched with Emotion Analysis:

{
"text": "The stockholders were pleased that Acme Corporation plans to build a new factory in Atlanta, Georgia.",
"enriched_text": {
"emotion": {
"document": {
"emotion": {
"disgust": 0.102578,
Detect sentiment 

Use the built-in Watson Natural Language Processing (NLP) sentiment enrichment to analyze the sentiment that is expressed in text and indicate whether the text is positive, neutral, or negative.

To understand the sentiment of an entire document, apply this enrichment to a field that contains as much of the text from the document as possible, such as the text field.

To analyze sentiment in text from multiple fields at one time and capture the overall sentiment of the document, use the Content Mining application. For more information, see [Detecting phrases that express sentiment](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-cm-phrase-sentiment).



  Adding the enrichment 

To add the sentiment enrichment, complete the following steps:



1.  Open your project and go to the Manage collections page.
2.  Click to open the collection that you want to enrich.
3.  Open the Enrichments tab.
4.  Scroll to find and select the Sentiment enrichment.
5.  Choose one or more fields to apply the enrichment to.

You can apply enrichments to the text and html fields, and to custom fields that were added from uploaded JSON or CSV files or from the Smart Document Understanding (SDU) tool.
6.  Click Apply changes and reprocess.



Enrichments that you enable are applied to the documents in random order. For information about how to remove an enrichment, see [Managing enrichments](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-manage-enrichments).





  Example 



  Input 

"It is powerful and easy to use and integrate with third party applications."





  Response 

In the JSON output:



*  score = Sentiment score from -1 (negative) to 1 (positive)
*  label = positive, negative, or neutral
*  mixed = Indicates that the document expresses a combination of different sentiments



{
"sentiment": {
"score": 0.9255063900060722,
"mixed": false,
"label": "positive"
}
}
In such cases, the differences might not be readily discernible from the default expressive tone. But there are instances where the style can audibly enhance the voices' inherent ability to detect and express emotion. The differences are often detectable only on certain words and phrases.

Table 1 provides examples of each available style for the <express-as> element. To demonstrate the effect of the styles, the table provides two samples for each example. The first sample speaks the text with the default en-US_EmmaExpressive voice. The second sample speaks the same text with the same voice but with the indicated style. A request that uses the <express-as> element fails if the style is not one of the supported values or is omitted from the element.



Table 1. Speaking styles

 Style Example input text Audio sample 

 cheerful "Oh, that's good news. I am very happy for you!" Your browser does not support the audio tag. 
 "<express-as style='cheerful'>Oh, that's good news. I am very happy for you!</express-as>" Your browser does not support the audio tag. 
 empathetic "Oh, I'm sorry to hear that. I know how difficult that can be." Your browser does not support the audio tag. 
 "<express-as style='empathetic'>Oh, I'm sorry to hear that. I know how difficult that can be.</express-as>" Your browser does not support the audio tag. 
 neutral "A five-alarm fire early this morning claimed the lives of more than a dozen residents." Your browser does not support the audio tag. 
 "<express-as style='neutral'>A five-alarm fire early this morning claimed the lives of more than a dozen residents.</express-as>" Your browser does not support the audio tag. 
 uncertain "That's strange. Hmm, I don't know if I've seen this before." Your browser does not support the audio tag. 
 "<express-as style='uncertain'>That's strange.
[Text to Speech](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-gettingStarted) You can use Text to Speech's speech-synthesis capabilities to convert written text into natural-sounding speech. [View docs](https://cloud.ibm.com/docs/watson?topic=watson-keyservice) 
 [Tone Analyzer](https://cloud.ibm.com/docs/tone-analyzer?topic=tone-analyzer-gettingStarted) You can use Tone Analyzer to detect emotional and language tones in your written texts. [View docs](https://cloud.ibm.com/docs/watson?topic=watson-keyservice) 
 [Knowledge Studio](https://cloud.ibm.com/docs/tone-analyzer?topic=tone-analyzer-gettingStarted) You can use Knowledge Studio to understand the linguistic nuances, meaning, and relationships specific to your industry. [View docs](https://cloud.ibm.com/docs/watson?topic=watson-keyservice) 
 [Watson OpenScale](https://dataplatform.cloud.ibm.com/docs/content/wsj/model/getting-started.html) You can use Watson OpenScale to automate and maintain the AI lifecycle in your business applications. [View docs](https://cloud.ibm.com/docs/watson?topic=watson-keyservice) 
 [IBM Watson® Assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-getting-startedgetting-started) You can use IBM Watson® Assistant to to build your own branded live chatbot into any device, application, or channel. [View docs](https://cloud.ibm.com/docs/watson?topic=watson-keyservice)