vania-janet/multiturn-rag-retrieval-data huggingface dataset:
In the JSON editor, add a [connect_to_agent response](https://cloud.ibm.com/docs/assistant?topic=assistant-phone-context), specifying your phone number as the sip.uri (replace {phone_number} with the phone number of your SIP trunk):



{
"output": {
"generic": [
{
"response_type": "connect_to_agent",
"transfer_info": {
"target": {
"service_desk": {
"sip": {
"uri": "sip:+{phone_number}@flex.twilio.com",
"transfer_headers_send_method": "refer_to_header"
}
}
}
},
"agent_available": {
"message": "Ok, I'm transferring you to an agent"
},
"agent_unavailable": {
"message": ""
}
}
]
}
}
Show more

Note that this example does not show how to use the context passed from Watson Assistant to Twilio Flex. You can reference the User-to-User information from within the Twilio Flex flow as follows:

{
"context": {
"widgets": {
"redirect_1": {
"User-to-User": "value",
}
}
}
}

where redirect_1 is the name of your redirect widget. For example, if you set up multiple queues, you might want to use a Twilio Split widget to pick a queue based on the returned context.





 Test your assistant 

Your assistant should now be able to answer phone calls to your phone number and transfer calls back to your Twilio Flex flow. To test your assistant:



1. Call your phone number. When the assistant responds, ask for an agent.
2.
For more information, see [Integrating with phone](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone).

Introducing the Twilio messaging integration!
: Enable your assistant to receive and respond to questions that customers submit by using SMS text messaging. When you enable both new integrations, your assistant can send text messages to a customer in the context of an ongoing phone conversation. For more information, see [Integrating with Twilio messaging](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-sms).

The Phone and Twilio messaging integrations are available as beta features in Watson Assistant service instances that are hosted in Dallas, Frankfurt, and Washington, DC.

The web chat integration is added to new assistants automatically
: Much like the Preview link integration, the Web chat integration now is added to the My first assistant assistant that is created for new users automatically.





 24 September 2020 

Introducing the containment metric!
: Want a quick way to see how often your assistant has to ask for help? Enable the new containment metric to find out. The containment metric measures the rate at which your assistant is able to address a customer's goal without human intervention. For conversations that are not contained, you can review the logs to understand what led customers to seek help outside of the assistant. For the metric to work, you must design your dialog to flag requests for additional support when they occur. For more information, see [Graphs and statistics](https://cloud.ibm.com/docs/assistant?topic=assistant-logs-overviewlogs-overview-graphs).

Chat transfer improvements
: When you add the Connect to human agent response type to a dialog node, you can now define messages to show to your customers during the transfer, and can specify service desk agent routing preferences. For more information, 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).





 22 September 2020 

New API version
: The current v2 API version is now 2020-09-24.
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).



 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 page, click the ![Try it](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/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/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/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/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/test_dialog_output.png)
4.
[Currency](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infocustomer-response-type-currency) An amount of money, including the unit. $25, 500 yen 
 [Percent](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infocustomer-response-type-percent) A fractional numeric value that is expressed as a percentage. 10%, 50 percent 
 [Free text](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infocustomer-response-type-free-text) Any arbitrary text response. 123 Main Street, John Q. Smith 







 Skipping steps, always asking steps, or never asking steps 

Although a customer response is associated with a particular step, the assistant can recognize the required information at any point during the action. You can set a step to be skipped if its value is already provided in the user's input. If the value is specified after the step, the new value replaces the value that is specified in the step itself.

For example, if the customer's initial input was I want to withdraw money from my checking account, a step that asks the user to select a bank account is skipped because the customer already entered that information.

For steps that expect a customer response, you can decide whether to:



* Skip asking if the answer is mentioned in previous messages. This is the default for responses except Confirmation and Free text.
* Always ask for this information, regardless of previous messages. This is the default for Confirmation and Free text.
* Never ask. Collect information from previous messages.





 Always ask 

If your action asks for the same type of data in more than one step, use the Always ask for this information setting to prevent the assistant from making incorrect assumptions. For example, you might have an action in which one step asks for a hotel check-in date and another step asks for the check-out date. If you skip asking, the assistant can mistake the check-in date for the check-out date.

To require that a step is always used in the conversation with a customer:



1.
Integrating with phone and Genesys Cloud 

IBM Cloud

You can use the phone integration to help your customers over the phone and transfer them to live agents inside of Genesys Cloud. If, in the course of a conversation with your assistant, a customer asks to speak to a person, you can transfer the conversation directly to a Genesys Cloud agent.



 Before you begin 

To use this integration pattern, make sure you have the following:



* Watson Assistant Plus or Enterprise Plan (required for phone integration)
* A working assistant you are ready to deploy
* A Genesys Cloud account







 Integrating with Genesys Cloud 

To integrate your assistant with Genesys Cloud, follow these steps:



1. Log into the [Genesys Cloud console](https://apps.mypurecloud.com).
2. Click Admin.
3. On the Telephony tab, click Trunks.
4. In the External Trunks section, click Create new. Specify the following information:



* In the External Trunk Name field, type a descriptive name (for example, Watson).
* In the Type field, select BYOC Carrier and then Generic BYOC Carrier.
* In the Inbound SIP Termination Identifier field, specify any name you want to use (for example, Watson). This value will not be used for now, but it is required by Genesys Cloud.



![Genesys create trunk](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/phone-genesys-create-trunk.png)
5. Under Outbound, scroll to the SIP Servers or Proxies section. Specify the following information:



* In the Hostname or IP Address field, type the SIP URI (not including sips:) from your Watson Assistant phone integration settings.
* In the Port field, type 5060.



Click the + button.

Currently, SIPS and digest authentication are supported.
6.
If you do not want to continue with the current action, click End this action after the other action is completed. You might use this option in cases where the customer decides to do something different; in this case, you want the conversation flow to switch to the subaction and not return.

By default, the assistant returns to the current action after the subaction completes. Any action variables or session variables that are defined in the subaction are accessible from subsequent steps in the calling action.
4. Click Apply.





 Passing values to a subaction 

Optionally, you can pass values to the subaction so the customer does not need to specify them again. For example, if your order-placement action collects the customer's name, you can then pass that information to the account-creation subaction. The step in the subaction that asks for the customer's name is skipped, and the value that is already specified is used instead.

To pass values to the subaction:



1. Click Edit passed values.
2. In the Edit passed variables window, click Set new value.
3. Select an action variable that you want to pass a value for. (The available action variables are based on the customer responses that are defined in the subaction.)
4. Select the value that you want to pass from the current action. You can select any available variable, or select Expression if you want to specify a different value.
5. Click Apply.









 Use an extension 

You can call an extension that has been added to your assistant in order to interact with an external service. For example, you might use an extension to interact with a ticketing or customer relationship management (CRM) system, or to retrieve real-time data such as mortgage rates or weather conditions. For more information about calling an extension, see [Calling an extension](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-call-extension).





 Search for the answer !
The behavior has not changed for messages that specify both intents and entities, or for messages that specify neither.
* The option to mark user input as irrelevant is now available for all supported languages. This is a beta feature.
* A new Credentials tab provides a single place where you can find all of the information you need for connecting your application to a workspace (such as the Watson Assistant credentials and workspace ID), as well as other deployment options. To access the Credentials tab for your workspace, click the icon and select Credentials.







 9 March 2017 

REST API updates
: The Watson Assistant REST API now supports access to the following resources:



* workspaces
* intents
* examples
* counterexamples



For more information, see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v1).





 7 March 2017 

Intent name restrictions
: The use of . or .. as an intent name causes problems and is no longer supported. You cannot rename or delete an intent with this name; to change the name, export your intents to a file, rename the intent in the file, and import the updated file into your workspace. Paying customers can contact support for a database change.





 1 March 2017 

System entities are now enabled in German
: System entities are now enabled in German.





 22 February 2017 

Messages are now limited to 2,048 characters
: Messages are now limited to 2,048 characters.





 3 February 2017 

Updates
: This release includes the following updates:



* We changed how intents are scored and added the ability to mark input as irrelevant to your application. For details, see [Defining intents](https://cloud.ibm.com/docs/assistant?topic=assistant-intents) and search for Mark as irrelevant.
* This release introduced a major change to the workspace. To benefit from the changes, you must manually upgrade your workspace.
* The processing of Jump to actions changed to prevent loops that can occur under certain conditions.
For more information about using the JSON editor to add responses, see [Defining responses using the JSON editor](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-assistant-responses-json).





 Applying advanced settings to the Speech to Text service 

Use the speech_to_text response type to send configuration commands to the Speech to Text service instance used by the phone integration. By sending a speech_to_text response from an action step, you can dynamically change the Speech to Text configuration during a conversation.

By default, any Speech to Text configuration changes you make persist for the remainder of the conversation, or until you update them again. You can change this behavior by specifying the update_strategy property of the parameters object.

The format of the speech_to_text response type is as follows:

{
"generic": [
{
"response_type": "speech_to_text",
"command_info": {
"type": "<command type>",
"parameters": {
"parameter name1": "parameter value",
"parameter name2": "parameter value"
}
}
}
]
}

Each command type along with its related parameters are described in the following sections.



 command_info.type : configure 

Dynamically reconfigures the Speech to Text service by applying a set of configuration parameters, which can be based on the conversation flow. For example, you might want to choose a particular customization ID or grammar at a specific point in the conversation.



 parameter description required default 

 narrowband_recognize The Speech to Text service configuration to use for narrowband codecs (such as PCMU and PCMA, which are sampled at 8 kHz). The parameters defined by this object are used when connecting to the Speech to Text service for speech recognition requests. For more information about these parameters, see the [Speech to Text API documentation](https://cloud.ibm.com/apidocs/speech-to-textWSRecognizeMethod). no Current Speech to Text configuration
options[].value.input.text string The text that will be sent to your assistant for the option. N 







 Example 

This example displays two options:



* Option 1 (labeled Buy something) sends a simple string message (Place order), which is sent to the workspace as the input text.
* Option 2 (labeled Exit) sends a complex message that includes both input text and an array of intents. The response can include any field that is a valid part of a Watson Assistant message. (For more information about the structure of message input, see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-data-v2message).)



{
"output": {
"generic":[
{
"response_type": "option",
"title": "Choose from the following options:",
"preference": "button",
"options":
{
"label": "Buy something",
"value": {
"input": {
"text": "Place order"
}
}
},
{
"label": "Exit",
"value": {
"input": {
"text": "Exit"
},
"intents":
{
"intent": "exit_app",
"confidence": 1.0
}
]
}
}
]
}
]
}
}
Show more







 Pause 

Pauses before sending the next message to the channel, and optionally sends a user is typing event (for channels that support it).



 Fields 



 Name Type Description Required? 

 response_type enum pause Y 
 time int How long to pause, in milliseconds. Y 
 typing boolean Whether to send the user is typing event during the pause. Ignored if the channel does not support this event. N 







 Example 

This examples sends the user is typing event while pausing for 5 seconds.

{
"output": {
What day would you like to come in?
>> Next Monday
What time works for you?
>> 10 AM
OK, Robert. You have an appointment for 10:00 AM on Sep 12. See you then!

Success! The application now uses the Watson Assistant service to understand natural-language input, and it displays the appropriate responses.

This simple example illustrates how you can build a custom client app to communicate with the assistant. Of course, a real-world application would use a more sophisticated user interface, and it might integrate with other applications such as a customer database or other business systems. It would also need to send additional data to the assistant, such as a user ID to identify each unique user. But the basic principles of how the application interacts with the Watson Assistant service would remain the same.





 Using the v1 runtime API 

Using the v2 API is the recommended way to build a runtime client application that communicates with the Watson Assistant service. However, some older applications might still be using the v1 runtime API, which includes a similar method for sending messages to the workspace within a dialog skill. Note that if your app uses the v1 runtime API, it communicates directly with the workspace, bypassing the skill orchestration and state-management capabilities of the assistant.

For more information about the v1 /message method and context, see the [v1 API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v1message).
If the input does not answer the question, and it does not match any existing action of the assistant, a step validation error results. For more information about validation errors and how they are handled, see [Handling errors in the conversation](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-handle-errors).
3. If the input matches a different action, the assistant switches to the matching action. The assistant changes to the new action if it has a confidence score match of 20% or higher. In the example, the customer's response (What's a CVV number?) is not a valid response, but it does match another action that is designed to answer this question. The matching action is triggered, answering the customer's question.
4. After the second action completes, the assistant asks the customer if they want to return to the original action. If they say Yes, the assistant continues with the step where the customer changed the topic. In the example, the assistant returns to the original action and repeats the question What is your CVV number?.







 Enabling and disabling changing the topic 

By default, the Change conversation topic feature is enabled for all assistants and actions. (You need to enable the feature for steps that use a free text or regex response. For more information, see [Enabling changing the topic for free text and regex customer responses](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-change-topicchange-topic-free-text-regex).)

However, some processes are best completed without interruption, so you might want to disable this feature. You can disable for all actions, or just for an individual action.

To disable changing the topic for all actions:



1. From the Actions page of the assistant, click Global settings![Gear icon](https://cloud.ibm.com/docs-content/v1/content/icons/settings.svg).
2. On the Change conversation topic tab, set the switch to Off.
3. Click Save, and then click Close.
Assistants 

An assistant is a cognitive bot that you can customize for the unique needs of your business. You teach it about the types of things your customers want to know and do, and then design a script for the assistant to follow as it converses with your customers to help them accomplish their business goals.

![Skills](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/skill-icon.png) An assistant routes your customer queries to a skill, which then provides the appropriate response. Dialog skills return responses that are authored by you to answer common questions, while search skills search for and return passages from existing self-service content to answer more complex inquiries.



 Dialog skill 

A dialog skill can understand and address questions or requests that your customers typically need help with. You provide information about the subjects or tasks your users ask about, and how they ask about them, and the product dynamically builds a machine learning model that is tailored to understand the same and similar user requests.



 Dialog tree Graphical user interface 

 You can use graphical tools to create a dialog for your assistant to read from when interacting with your users, a dialog that simulates a real conversation. The dialog keys off the common customer goals that you teach it to recognize, and provides useful responses. ![A sample dialog tree with example content](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/dialog-depiction.png) 



The dialog skill itself is defined in text, but you can integrate it with Watson Speech to Text and Watson Text to Speech services that enable users to interact with your assistant verbally.

!
[An ending node was added to the dialog also.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/gs-ending-node-added.png)





 Testing intent recognition 

You built a simple dialog to recognize and respond to both greeting and ending inputs. Let's see how well it works.



1. Click the ![Try it](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/try-it.png) icon to open the Try it out pane. There's that reassuring welcome message.
2. In the text field, type Hello and press Enter. The output indicates that the General_Greetings intent was recognized, and the appropriate response (Good day to you.) is displayed.
3. Try the following input:



* bye
* howdy
* see ya
* good morning
* sayonara





Watson can recognize your intents even when your input doesn't exactly match the examples that you included. The dialog uses intents to identify the purpose of the user's input regardless of the precise wording used, and then responds in the way you specify.





 Result of building a dialog 

That's it. You created a simple conversation with two intents and a dialog to recognize them.







 Next steps 

This tutorial is built around a simple example. For a real application, you need to define some more interesting intents, some entities, and a more complex dialog that uses them both. When you have a polished version of the assistant, you can make API calls to it from your client application.



* Complete follow-on tutorials that build more advanced dialogs: