vania-janet/multiturn-rag-retrieval-data huggingface dataset:
As part of work being done to help the assistant learn automatically from user choices, the order of the options in the disambiguation list is being randomized on purpose. Changing the order helps to avoid bias that can be introduced by a percentage of people who always pick the first option without first reviewing their choices.









 12 November 2019 

Slot prompt JSON editor
: You can now use the context or JSON editors for the slot response field where you define the question that your assistant asks to get information it needs from the customer. For more information about slots, see [Gathering information with slots](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-slots).

New South Korea location
: You can now create Watson Assistant instances in the Seoul location. As with other locations, the IBM Cloud Seoul location uses token-based Identity and Access Management (IAM) authentication.

Technology preview
: A technology preview experience was released. A select set of new users are being presented with a new user interface that takes a different approach to building an assistant.





 7 November 2019 

Irrelevance detection has been added
: When enabled, a supplemental model is used to help identify utterances that are irrelevant and should not be answered by the dialog skill. This new model is especially beneficial for skills that have not been trained on what subjects to ignore. This feature is available for English skills only. For more information, see [Irrelevance detection](https://cloud.ibm.com/docs/assistant?topic=assistant-irrelevance-detection).

Time zone support for now() method
: You can now specify the time zone for the date and time that is returned by the now() method. See [Now()](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-methodsdialog-methods-dates-now).





 24 October 2019 

Testing improvement
: You can now see the top three intents that were recognized in a test user input from the "Try it out" pane.
Refer-To: sip:user@domain.com?User-to-User=637573746f6d2d757365722d746f2d75736572%3Bencoding%3Dhex&X-Watson-Assistant-Session-History-Key=dev::latest::893499::dff9c274-adc4-4f63-93de-781166760bf8::978f1fd7-4e24-47d8-adb0-24a8a6eff69e::b5ffd6c2-902f-4658-b586-e3fc170a6cf3::7ad616a350cc48078f17e3ee3df551de
Contact: sip:a@atlanta.example.com
Content-Length: 0

For Twilio Flex, the User-to-User header will use encoding=ascii.







 Playing hold music or a voice recording 

To play hold music or to play a recorded message, use the audio response type. For more information about using response types, see [Defining responses using the JSON editor](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-assistant-responses-json).

You cannot play hold music during a call transfer. However, you might want to play hold music if your assistant needs time to perform processing of some kind, such as calling a client-side action or making a call to a webhook.

The phone integration supports the following properties for the audio response type:



 Property Description 

 source The URL of a publicly-accessible .wav audio file. The audio file must be single channel (mono) and PCM-encoded, and must have an 8,000 Hz sampling rate with 16 bits per sample. 
 channel_options.voice_telephony.loop Whether to repeatedly restart the audio playback after it finishes. The default value is false. 



If you set channel_options.voice_telephony.loop to true, add a user-defined response with the vgwActForceNoInputTurn command.
response_timestamp>=2020-07-01,response_timestamp<2020-08-01 
 The timestamp of the response is earlier than 2019-11-01T04:00:00.000Z. response_timestamp<2019-11-01T04:00:00.000Z 
 The message is labeled with the customer ID my_id. customer_id::my_id 
 The message was sent to a specific assistant. assistant_id::dcd5c5ad-f3a1-4345-89c5-708b0b5ff4f7 
 The user input text contains the word "order" or a grammatical variant (for example, orders or ordering. request.input.text:order 
 An intent name in the response exactly matches place_order. response.output.intents:intent::place_order 
 An entity name in the response exactly matches beverage. response.output.entities:entity::beverage 
 No intent name in the response exactly matches order. response.intents:intent::!order 
 The user input text does not contain the word "order" or a grammatical variant. request.input.text:!order 
 The user input text contains the string !hello. request.input.text:!hello 
 The user input text contains the string IBM Watson. request.input.text:"IBM Watson" 
 The user input text contains a string that has no more than 2 single-character differences from Watson. request.input.text:Watson2 
 The user input text contains a string consisting of comm, followed by zero or more additional characters, followed by s. request.input.text:comms 
 An intent name in the response exactly matches either hello or goodbye. response.output.intents:intent::(hello goodbye) 
 An intent name in the response exactly matches order, and an entity name in the response exactly matches beverage. [response.output.intents:intent::order,response.output.entities:entity::beverage] 







 Filtering v1 logs 

If your application is still using the v1 API, you can query and filter logs using the v1 /logs method.
For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 correlation_ID The unique identifier that is used to track and correlate transactions. 
 new_rotation_interval Required. An integer value that determines the key rotation interval time in months. The minimum is 1 and the maximum is 12. 



A successful PUT api/v2/keys/{id}/policies response returns updated policy details that are associated with your key. The following JSON object shows an example response for a root key with an updated rotation policy.

{
"metadata": {
"collectionTotal": 1,
"collectionType": "application/vnd.ibm.kms.policy+json"
},
"resources": [
{
"id": "a1769941-9805-4593-b6e6-290e42dd1cb5",
"rotation": {
"interval_month": 2
},
"createdby": "IBMid-503CKNRHR7",
"createdat": "2019-03-06T16:31:05Z",
"updatedby": "IBMid-820DPWINC2",
"updatedat": "2019-03-10T12:24:22Z"
}
]
}

The interval_month and updatedat values are updated in the policy details for the key. If a different user updates a policy for a key that you created initially, the updatedby value also changes to show the identifier for the person who sent the request.









 What's next
https://{location}.assistant.watson.cloud.ibm.com/{location}/{instance-id}/skills/{skill-id}/build/dialognode={node-id}
4. Edit the URL by replacing the current {node-id} value with the ID of the node you want to find, and then submit the new URL.
5. If necessary, highlight the edited URL again, and resubmit it.



The page refreshes, and shifts focus to the dialog node with the node ID that you specified. If the node ID is for a slot, a Found or Not found slot condition, a slot handler, or a conditional response, then the node in which the slot or conditional response is defined gets focus and the corresponding modal is displayed.

If you still cannot find the node, you can export the dialog skill and use a JSON editor to search the skill JSON file.



 How many nodes are in my dialog? 

To see the number of dialog nodes in a dialog skill, do one of the following things:



* If it is not associated with an assistant already, add the dialog skill to an assistant, and then view the skill tile from the main page of the assistant. The trained data section lists the number of dialog nodes.
* Send a GET request to the /dialog_nodes API endpoint, and include the include_count=true parameter. For example:

curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes?version=2018-09-20&include_count=true"

where {url} is the appropriate URL for your instance. For more details, see [Service endpoint](https://cloud.ibm.com/apidocs/assistant/assistant-v1service-endpoint).

In the response, the total attribute in the pagination object contains the number of dialog nodes.



If the total seems larger than you expected, it might be because the dialog that you build from the application is translated into a JSON object.
text-to-speech.speaker.delete Delete a speaker (DELETE /v1/speakers/{speaker_id}). 
 text-to-speech.custom-model-prompt.delete Delete a prompt from a custom model (DELETE /v1/customizations/{customization_id}/prompts/{prompt_id}). 









 GDPR event 

The following table lists the Text to Speech action for General Data Protection Regulation (GDPR) that generates an event.



Table 8. GDPR .delete action that generates an event

 Action Description 

 text-to-speech.gdpr-user-data.delete Delete information for a user (DELETE /v1/user_data). 







 Where to view events 

Events that are generated by an instance of the Text to Speech service are automatically forwarded to the IBM Cloud Activity Tracker service instance that is available in the same location.

IBM Cloud Activity Tracker can have only one instance per location. To view events, you must access the web user interface (UI) of the IBM Cloud Activity Tracker service in the same location where your service instance is available. For more information, see [Navigating to the UI](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-launch).
For more information, see [Integrating with SMS](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-sms).

When you exchange a text with a customer during a conversation, the assistant initiates the SMS message exchange. It sends a text message to the user and asks for the user to respond to it.

To send a specific message from an action step, use the user_defined response type with the vgwActSendSMS command:

{
"generic": [
{
"response_type": "text",
"values":
{
"text": "I will send you a text message now."
}
],
"selection_policy": "sequential"
},
{
"response_type": "user_defined",
"user_defined": {
"vgwAction": {
"command": "vgwActSendSMS",
"parameters": {
"message": "Hey, this is Watson Assistant. To send me your street address, respond to this text message with your address."
}
}
}
}
]
}
Show more

You can specify any of the following parameters in the parameters object:



 Parameter Type Description 

 message string The text of the SMS message to send. Required. 
 mediaURL list A list of URLs for media files to be sent with the message as MMS attachments. Optional. 
 tenantPhoneNumber string The phone number that is associated with the tenant. The format of the number must match the format that is required by the SMS provider. If no tenantPhoneNumber value is provided, the tenant ID from the phone integration configuration for the active call is used. Optional. 
 userPhoneNumber string The phone number to send the SMS message to. The format of the number must match the format that is required by the SMS provider. If no userPhoneNumber value is provided, the voice caller's phone number from From header of the incoming SIP INVITE request is used. Optional.
"skills": {
"main skill": {
"user_defined": {
"my_context_var": "this is the value"
}
}
}
}

For detailed information about how to access context variables using the API, see the [v2 API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2).



 Example 

The following example shows a stateful /message request that includes both global and skill-specific context variables; it also uses the options.return_context property to request that the context be returned with the response. Note that this option is applicable only if you are using the stateful message method, because the stateless message method always returns the context.



* Java
* Python
* Node



MessageInputOptions inputOptions = new MessageInputOptions.Builder()
.returnContext(true)
.build();

MessageInput input = new MessageInput.Builder()
.messageType("text")
.text("Hello")
.options(inputOptions)
.build();

// create global context with user ID
MessageContextGlobalSystem system = new MessageContextGlobalSystem.Builder()
.userId("my_user_id")
.build();
MessageContextGlobal globalContext = new MessageContextGlobal.Builder()
.system(system)
.build();

// build user-defined context variables, put in skill-specific context for main skill
Map<String, Object> userDefinedContext = new HashMap<>();
userDefinedContext.put("account_number","123456");
MessageContextSkill mainSkillContext = new MessageContextSkill.Builder()
.userDefined(userDefinedContext)
.build();
Map<String, MessageContextSkill> skillsContext = new HashMap<>();
The default is en-US_BroadbandModel. For more information, see [Using the default model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-usemodels-use-default).

language_customization_id (optional string)
: The GUID of a custom language model that is to be used with the request.

acoustic_customization_id (optional string)
: The GUID of a custom acoustic model that is to be used with the request.

base_model_version (optional string)
: The version of the specified base model that is to be used with the request.







 JSON metadata for multipart requests 

The JSON metadata that you pass with a multipart request can include the following fields:



* part_content_type (string)
* data_parts_count (integer)
* customization_weight (number)
* inactivity_timeout (integer)
* keywords (string[])
* keywords_threshold (number)
* max_alternatives (integer)
* word_alternatives_threshold (number)
* word_confidence (boolean)
* timestamps (boolean)
* profanity_filter (boolean)
* smart_formatting (boolean)
* speaker_labels (boolean)
* grammar_name (string)
* redaction (boolean)
* end_of_phrase_silence_time (double)
* split_transcript_at_phrase_end (boolean)
* speech_detector_sensitivity (number)
* background_audio_suppression (number)
* low_latency (boolean)
* character_insertion_bias (float)



Only the following two parameters are specific to multipart requests:



* The part_content_type field is optional for most audio formats. It is required for the audio/alaw, audio/basic, audio/l16, and audio/mulaw formats. It specifies the format of the audio in the following parts of the request. All audio files must be in the same format.
Phone integration context variables 

You can use context variables to manage the flow of conversations with customers who interact with your assistant over the telephone.

The following tables describe the context variables that have special meaning in the context of the phone integration. They should not be used for any purpose other than the documented use.



 Context variables that are set by the phone channel 



Context variables set by the phone channel

 Name Type Description 

 sip_call_id string The SIP call ID associated with the Watson Assistant session. 
 sip_custom_invite_headers object A JSON object containing key/value pairs defining SIP headers that are pulled from the initial SIP INVITE request and passed to the Watson Assistant service (for example, {"Custom-Header1": "123"}). 
 private.sip_from_uri string The SIP From URI associated with the Watson Assistant service. 
 private.sip_request_uri string The SIP request URI that started the conversation session. 
 private.sip_to_uri string The SIP To URI associated with the conversation session. 
 private.user_phone_number string The phone number that the call was received from. 
 assistant_phone_number string The phone number associated with the Watson Assistant side that received the phone call. 







 Input parameters that are set by the phone channel 

The following input parameters are only valid for the current conversation turn.



Input parameters set by the phone channel

 Name Type Description 

 post_response_timeout_occurred boolean Whether the post response timeout expired. 
 barge_in_occurred boolean Whether barge-in occurred. 
 final_utterance_timeout_occurred true or false Whether the final utterance timeout expired. 
 dtmf_collection_succeeded boolean Whether the DTMF collection succeeded or failed. When true, a DTMF collection succeeded, and returns the expected number of digits. When false, a DTMF collection failed to collect the specified number of digits. Even when dtmf_collection_succeeded is false, all collected digits are passed to the dialog in the input string of the turn request. 
 is_dtmf boolean Whether the input to Watson Assistant is dual-tone multi-frequency signaling (DTMF).
1.07, <br>1.53 <br>"yeah", "from": 1.07, <br>"to": 1.53, <br>"speaker": 1, <br>"confidence": 0.63, <br>"final": false 2.45, <br>3.03 <br>"Billy", "from": 2.45, <br>"to": 3.03, <br>"speaker": 2, <br>"confidence": 0.55, <br>"final": false 
 1.66, <br>2.02 <br>"yeah", "from": 1.66, <br>"to": 2.02, <br>"speaker": 2, <br>"confidence": 0.54, <br>"final": false 3.57, <br>3.95 <br>"good", "from": 3.57, <br>"to": 3.95, <br>"speaker": 1, <br>"confidence": 0.63, <br>"final": true 



The results clearly capture the brief two-person exchange:



* Speaker 2 - "Hello?"
* Speaker 1 - "Yeah?"
* Speaker 2 - "Yeah, how's Billy?"
* Speaker 1 - "Good."



In the example, the final field for each speaker label but the last is false. The service sets the final field to true only for the last speaker label that it returns. That value of true indicates that the service has completed its analysis of the speaker labels.





 Speaker IDs for speaker labels 

The example also illustrates an interesting aspect of speaker IDs. In the speaker fields, the first speaker has an ID of 2 and the second has an ID of 1. The service develops a better understanding of the speaker patterns as it processes the audio. Therefore, it can change speaker IDs for individual words, and can also add and remove speakers, until it generates its final results.

As a result, speaker IDs might not be sequential, contiguous, or ordered. For instance, IDs typically start at 0, but in the previous example the earliest ID is 1.
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).



 Personalizing the dialog with context 

To personalize the conversation, your assistant can collect information from the customer and then refer back to it later in the conversation.



 Retaining information across dialog turns 

The dialog in a dialog skill is stateless, meaning that it does not retain information from one interaction with the user to the next. When you add a dialog skill to an assistant and deploy it, the assistant saves the context from one message call and then re-submits it on the next request throughout the current session. The current session lasts for as long a user interacts with the assistant plus the designated session inactivity time frame. The maximum session inactivity time allowed ranges from 5 minutes to 7 days, depending on your plan type. If you do not add the dialog skill to an assistant, it is your responsibility as the custom application developer to maintain any continuing information that the application needs.

The application can pass information to the dialog, and the dialog can update this information and pass it back to the application, or to a subsequent node. The dialog does so by using context variables.





 Context variables 

A context variable is a variable that you define in a node. You can specify a default value for it. Other nodes, application logic, or user input can subsequently set or change the value of the context variable.

You can condition against context variable values by referencing a context variable from a dialog node condition to determine whether to execute a node. You can also reference a context variable from dialog node response conditions to show different reponses depending on a value provided by an external service or by the user.

Learn more:



* [Passing context from the application](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-runtime-contextdialog-runtime-context-from-app)
For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token). 
 instance_ID Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 key_ring_ID Optional. The unique identifier of the target key ring. If unspecified, the response will include all resources that the user has access to in the specified instance. If provided, the response will only include resources that the user has access to in the specified key ring. For more information, see [Grouping keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys). 
 correlation_ID Optional.The unique identifier that is used to track and correlate transactions. 



A successful GET api/v2/keys request returns a collection of keys that are available in your Key Protect service instance.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 2
},
"resources": [
{
"id": "02fd6835-6001-4482-a892-13bd2085f75d",
"type": "application/vnd.ibm.kms.key+json",
"name": "Root-key",
"state": 1,
[Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-overview). 
 Digression A feature that gives the user the power to direct the conversation. It prevents customers from getting stuck in a dialog thread; they can switch topics whenever they choose. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-runtimedialog-runtime-digressions). 
 Disambiguation A feature that enables the assistant to ask customers to clarify their meaning when the assistant isn't sure what a user wants to do next. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-runtimedialog-runtime-disambiguation). 
 Entity Information in the user input that is related to the user's purpose. An intent represents the action a user wants to do. An entity represents the object of that action. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-entities). 
 Integrations Ways you can deploy your assistant to existing platforms or social media channels. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-integration-add). 
 Intent The goal that is expressed in the user input, such as answering a question or processing a bill payment. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-intents). 
 Message A single turn within a conversation that includes a single call to the /message API endpoint and its corresponding response. 
 Monthly active user (MAU) A single unique user who interacts with an assistant one or many times in a given month. 
 Preview link An integration that builds embeds your assistant in a chat window that is displayed on an IBM-branded web page. From the preview link integration, you can test how a conversation flows through any and all skills that are attached to your assistant, from end to end.