vania-janet/multiturn-rag-retrieval-data huggingface dataset:
* [Get a custom prompt](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechgetcustomprompt): GET /v1/customizations/{customization_id}/prompts/{prompt_id}
* [Delete a custom prompt](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechdeletecustomprompt): DELETE /v1/customizations/{customization_id}/prompts/{prompt_id}



* The service includes four methods for working with speaker models:



* [Create a speaker model](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechcreatespeakermodel): POST /v1/speakers
* [List speaker models](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechlistspeakermodels): GET /v1/speakers
* [Get a speaker model](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechgetspeakermodel): GET /v1/speakers/{speaker_id}
* [Delete a speaker model](https://cloud.ibm.com/apidocs/text-to-speech/text-to-speechdeletespeakermodel): DELETE /v1/speakers/{speaker_id}





Activity Tracker actions are available for all new Tune by Example events. For more information, see [Tune by Example events](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-at-eventsat-events-tbe).

Updates to Activity Tracker actions for customization
: The names of the actions for the Activity Tracker events for the customization methods have changed. The actions now include the string custom-model instead of custom-voice. The old names of the actions are deprecated. The old names are still available for use but will be removed at a future date.
For more information, see [Ending the conversation gracefully](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-startdialog-start-anything-else).

The containment and coverage metrics are available to Plus or Enterprise plan users.
* Total conversations: The total number of conversations between active users and your assistant during the selected time period. This number counts exchanges in which the welcome message is displayed to a user, even if the user doesn't respond.
* Average messages per conversation - The total messages received during the selected time period divided by the total conversations during the selected time period.
* Total messages - The total number of messages received from active users over the selected time period.
* Active users - The number of unique users who have engaged with your assistant within the selected time period.
* Average conversations per user - The total conversations divided by the total number of unique users during the selected time period.

Statistics for Active users and Average conversations per user require a unique user_id parameter to be specified with the messages. This value is typically specified by all integrations because it is used for billing purposes. For more information, see [User-based plans explained](https://cloud.ibm.com/docs/assistant?topic=assistant-admin-managing-planadmin-managing-plan-user-based).







 Controls 

You can use the following controls to filter the information:



* Time period control - Use this control to choose the period for which data is displayed. This control affects all data shown on the page: not just the number of conversations displayed in the graph, but also the statistics displayed along with the graph, and the lists of top intents and entities.

The statistics can cover a longer time period than the period for which logs of conversations are retained.

![Time period control](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/oview-time.png)

You can choose whether to view data for a single day, a week, a month, or a quarter.
{
"output": {
"generic": [!
{
"response_type": "text",
"text": "Welcome to the Watson Assistant example"
}
],
"intents": [
{
"intent": "hello",
"confidence": 1
}
],
"entities": []
},
"user_id": "my_user_id",
"context": {
"global": {
"system": {
"turn_count": 1,
"user_id": "my_user_id"
}
},
"skills": {
"main skill": {
"user_defined": {
"account_number": "123456"
}
}
}
}
}
Show more





 Restoring conversation state 

In some situations, you might want the ability to restore a conversation to a previous state.

You can use the export option on stateful message requests to specify that you want the context object in the response to include complete session state data. If you specify true for this option, the returned skill context includes an encoded state property that represents the current conversation state.

If you are using the stateful message API, the service stores conversation state data only for the life of the session. However, if you save this context data (including state) and send it back to the service with a subsequent message request, you can restore the conversation to the same state, even if the original session expired or was deleted.

If you are using the stateless message API, the state property is always included in responses (along with the rest of context). Although stateless sessions do not expire, you can still use this state data to reset a conversation to a previous state.
The suggestions are shown automatically in situations where the customer might otherwise become frustrated. For example, if a customer uses different wording to ask the same question multiple times in succession, and the same dialog node is triggered each time, then related topic suggestions are shown in addition to the triggered node's response. The suggestions that are offered give the customer a quick way to get the conversation back on track.

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

To enable suggestions, complete the following steps:



1. Open the Suggestion tab, and set the switch to On.

The Include a connection to support section is displayed where you can configure whether and how to give customers the ability to connect with support.
2. Decide when you want an option to connect with support to be shown in the suggestions list. The choices are:



* Always: Always shows the option to get support in the list of suggestions.
* Never: Never shows the option to get support in the list of suggestions.
* 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 dialog node for a second time in succession.



3. In the Option label field, add a label for the option.

The text in the Option label field has two functions:



* The text is shown in the suggestions list as an option for customers to select.
* When selected by a customer, the text is sent to your assistant as a new message. The label must be able to function as input that your dialog understands and knows how to handle.



By default, the option label Connect with agent is used. Change the option label to a message that helps your customers reach whatever form of support you do offer.
Improving your conversation 

Test your dialog, and organize your dialog nodes.



 Testing your dialog 

As you make changes to your dialog, you can test it at any time to see how the dialog responds to input.

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



1. From the Dialog tab, click the ![Try it](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/ask_watson.png) icon.
2. In the chat pane, type some text and then press Enter.

Make sure the system has finished training on your most recent changes before you start to test the dialog. If the system is still training, a message is displayed in the Try it out pane:

![Screen capture of training message](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/training.png)
3. Check the response to see if the dialog correctly interpreted your input and chose the appropriate response.

The chat window indicates what intents and entities were recognized in the input:

![Screen capture of test dialog output](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/test_dialog_output.png)
4. To see the top intents that were recognized in the test input along with their confidence scores, hover over the eye icon that is displayed next to the intent with the highest confidence score.

!
Defining what's irrelevant 

Teach your dialog skill to recognize when a user asks about topics that it is not designed to answer.

To teach your assistant about subjects it should ignore, you can review your user conversation logs to mark utterances that discuss off-topic subjects as irrelevant.

Intents that are marked as irrelevant are saved as counterexamples in the JSON workspace, and are included as part of the training data. They teach your assistant to explicitly not answer utterances of this type.

While testing your dialog, you can mark an intent as irrelevant directly from the Try it out pane.

![Mark as irrelevant screen capture](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/irrelevant.png)

Be certain before you designate an input as irrelevant.



* There is no way to access or change the inputs from the user interface later.
* The only way to reverse the identification of an input as being irrelevant is to use the same input in a test integration channel, and then explicitly assign it to an intent.



Often there are subjects that you expect customers to ask and that you want your assistant to address eventually, but that you aren't ready to fully implement yet. Instead of adding those topics as counterexamples which can be hard to find later, capture the customer input examples as new intents. But, don't link dialog nodes to the intents until you're ready. If customers ask about one of these topics in the meantime, the anything_else node is triggered to explain that the assistant can't help with the current request, but can help them with other things.



 Irrelevance detection 

A new irrelevance detection algorithm was introduced with version 1.5.0. The irrelevance detection model helps your dialog skill recognize subjects that you do not want it to address, even if you haven't explicitly taught it about what to ignore. This enhanced model helps your skill recognize irrelevant inputs earlier in the development process.
For example, you can use the syntax: @us_phone.groups[1] == '617' See [Storing and recognizing pattern entity groups in input](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-tipsdialog-tips-get-pattern-groups) for more information.
* Intent: The simplest condition is a single intent. The node is used if, after your assistant's natural language processing evaluates the user's input, it determines that the purpose of the user's input maps to the pre-defined intent. Use the syntax, intent_name. For example, weather checks if the user input is asking for a weather forecast. If so, the node with the weather intent condition is processed.

For more information about intents, see [Defining intents](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-intents).
* Special condition: Conditions that are provided with the product that you can use to perform common dialog functions. See the Special conditions table in the next section for details.







 Special conditions 



Special conditions

 Condition syntax Description 

 anything_else You can use this condition at the end of a dialog, to be processed when the user input does not match any other dialog nodes. The Anything else node is triggered by this condition. 
 conversation_start Like welcome, this condition is evaluated as true during the first dialog turn. Unlike welcome, it is true whether or not the initial request from the application contains user input. A node with the conversation_start condition can be used to initialize context variables or perform other tasks at the beginning of the dialog. 
 false This condition is always evaluated to false. You might use this at the start of a branch that is under development, to prevent it from being used, or as the condition for a node that provides a common function and is used only as the target of a Jump to action. 
 irrelevant This condition will evaluate to true if the user’s input is determined to be irrelevant by the Watson Assistant service. 
 true This condition is always evaluated to true.
Dialog overview 

The dialog uses the intents that are identified in the user's input, plus context from the application, to interact with the user and ultimately provide a useful response.

The dialog matches intents (what users say) to responses (what the bot says back). The response might be the answer to a question such as Where can I get some gas? or the execution of a command, such as turning on the radio. The intent and entity might be enough information to identify the correct response, or the dialog might ask the user for more input that is needed to respond correctly. For example, if a user asks, Where can I get some food? you might want to clarify whether they want a restaurant or a grocery store, to dine in or take out, and so on. You can ask for more details in a text response and create one or more child nodes to process the new input.

The dialog is represented graphically in Watson Assistant as a tree. Create a branch to process each intent that you want your conversation to handle. A branch is composed of multiple nodes.



 Dialog nodes 

Each dialog node contains, at a minimum, a condition and a response.

![Shows user input going to a box that contains the statement If: CONDITION, Then: RESPONSE](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/node1-empty.png)



* Condition: Specifies the information that must be present in the user input for this node in the dialog to be triggered. The information is typically a specific intent. It might also be an entity type, an entity value, or a context variable value. See [Conditions](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-builddialog-overview-conditions) for more information.
* Response: The utterance that your assistant uses to respond to the user. The response can also be configured to show an image or a list of options, or to trigger programmatic actions.
* Use the GET /v1/customizations/{customization_id}/prompts/{prompt_id} method to list information about a specified custom prompt from a custom model. For more information, see [Listing custom prompts](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-tbe-custom-promptstbe-custom-prompts-list).





It is a best practice to preserve this information in a format that you can use to re-create your customized resources in the event of a failure. Actively maintaining the information, and preparing the calls listed in the following section ahead of time, can enable you to recover as quickly as possible.





 Restoring custom models and speaker models 

If you need to recover from a disaster, you can use your backup information to re-create your custom models, custom entries, speaker models, and custom prompts:



1. To re-create your custom models, use the POST /v1/customizations method. For more information, see [Creating a custom model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModelscuModelsCreate).
2. To add multiple word/translation pairs to a custom model, use the POST /v1/customizations/{customization_id}/words method. For more information, see [Adding multiple words to a custom model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWordscuWordsAdd).
3. To add a single word/translation pair to a custom model, use the POST /v1/customizations/{customization_id}/words/{word} method. For more information, see [Adding a single word to a custom model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWordscuWordAdd).
4. To add a speaker model, use the POST /v1/speakers method.
For example, if you want to check whether the city entity is Dublin (Ohio), you must use @city == 'Dublin (Ohio)' instead of @city:(Dublin (Ohio)).





 Shorthand syntax for intents 

The following table shows examples of the shorthand syntax that you can use when referring to intents.



Intents shorthand syntax

 Shorthand syntax Full syntax in SpEL 

 `#help` `intent == 'help'` 
 `! #help` `intent != 'help'` 
 `NOT #help` `intent != 'help'` 
 `#help` or `#i_am_lost` `(intent == 'help' || intent == 'I_am_lost')` 









 Built-in global variables 

You can use the expression language to extract property information for the following global variables:



 Global variable Definition 

 context JSON object part of the processed conversation message. 
 entities[ ] List of entities that supports default access to 1st element. 
 input JSON object part of the processed conversation message. 
 intents[ ] List of intents that supports default access to first element. 
 output JSON object part of the processed conversation message. 







 Accessing entities 

The entities array contains one or more entities that were recognized in user input.

While testing your dialog, you can see details of the entities that are recognized in user input by specifying this expression in a dialog node response:

<? entities ?>

For the user input, Hello now, your assistant recognizes the @sys-date and @sys-time system entities, so the response contains these entity objects:

[
{"entity":"sys-date","location":6,9],"value":"2017-08-07",
"confidence":1,"metadata":{"calendar_type":"GREGORIAN",
"timezone":"America/New_York"}},
{"entity":"sys-time","location":6,9],"value":"15:01:00",
* Change conversation topic: In general, an action is designed to lead a customer through a particular process without any interruptions. In real life, however, conversations almost never follow such a simple flow. In the middle of a conversation, customers might get distracted, ask questions about related issues, misunderstand something, or just change their minds about what they want to do. The Change conversation topic feature enables your assistant to handle these digressions, dynamically responding to the user by changing the conversation topic as needed.
* Fallback action: The built-in action, Fallback, provides a way to automatically connect customers to a human agent if they need more help. This action helps you to handle errors in the conversation, and is triggered by these conditions:



* Step validation failed: The customer repeatedly gave answers that were not valid for the expected customer response type.
* Agent requested: The customer directly asked to be connected to a human agent.
* No action matches: The customer repeatedly made requests or asked questions that the assistant did not understand.





Dialog skill "Try it out" improvements
: For dialog skills, the Try it out pane now uses the [React](https://reactjs.org/) UI framework similar to the rest of the Watson Assistant user interface. You shouldn't see any change in behavior or functionality. As a part of the update, dialog skill error handling has been improved within the "Try it out" pane. This update will be implemented incrementally, starting with service instances in the Tokyo and Seoul data centers.





 2 September 2021 

Deploy your assistant on the phone in minutes
: We have partnered with [IntelePeer](https://intelepeer.com/) to enable you to generate a phone number for free within the phone integration. Simply choose to generate a free number when following the prompts to create a phone integration, finish the setup, and a number is assigned to your assistant. These numbers are robust and ready for production.

Connect to your existing service desks
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).



 Defining what's irrelevant 

Teach your dialog skill to recognize when a user asks about topics that it is not designed to answer.

To teach your assistant about subjects it should ignore, you can review your user conversation logs to mark utterances that discuss off-topic subjects as irrelevant.

Intents that are marked as irrelevant are saved as counterexamples in the JSON workspace, and are included as part of the training data. They teach your assistant to explicitly not answer utterances of this type.

While testing your dialog, you can mark an intent as irrelevant directly from the Try it out pane.

![Mark as irrelevant screen capture](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/irrelevant.png)

Be certain before you designate an input as irrelevant.



* There is no way to access or change the inputs from the user interface later.
* The only way to reverse the identification of an input as being irrelevant is to use the same input in a test integration channel, and then explicitly assign it to an intent.



Often there are subjects that you expect customers to ask and that you want your assistant to address eventually, but that you aren't ready to fully implement yet. Instead of adding those topics as counterexamples which can be hard to find later, capture the customer input examples as new intents. But don't link dialog nodes to the intents until you're ready. If customers ask about one of these topics in the meantime, the anything_else node is triggered to explain that the assistant can't help with the current request, but can help them with other things.



 Irrelevance detection 

The irrelevance detection feature helps your dialog skill recognize subjects that you do not want it to address, even if you haven't explicitly taught it about what to ignore. This feature helps your skill recognize irrelevant inputs earlier in the development process.