vania-janet/multiturn-rag-retrieval-data huggingface dataset:
![Example dialog 6](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/dialog_api_6.png)

Note that node_1, node_4, node_5, and node_7 were all deleted. When you delete a node, all descendants of that node are deleted as well. Therefore, if you delete a root node, you are actually deleting an entire branch of the dialog tree. Any other references to the deleted node (such as next_step references) are changed to null.

In addition, node_2 is updated to point to node_8 as its new previous sibling.





 Renaming a node 

Finally, let's rename node_2 using the POST /dialog_nodes/node_2 method with the following body:

{
"dialog_node": "node_X"
}

![Example dialog 7](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/dialog_api_7.png)

The structure of the dialog has not changed, but once again multiple nodes were modified to reflect the changed name:



* The parent properties of node_9 and node_6
* The previous_sibling property of node_3



Any other references to the deleted node (such as next_step references) are also changed.
delete-dialog-node Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, workspace_id, dialog_node Delete a dialog node. 
 get-dialog-node Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, workspace_id, dialog_node, include_audit Get a dialog node. 
 list-dialog-nodes Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, workspace_id, page_limit, include_count, sort, cursor, include_audit List dialog nodes. 
 update-dialog-node Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, workspace_id, dialog_node, new_dialog_node, new_description, new_conditions, new_parent, new_previous_sibling, new_output, new_context, new_metadata, new_next_step, new_title, new_type, new_event_name, new_variable, new_actions, new_digress_in, new_digress_out, new_digress_out_slots Update a dialog node. 
 list-all-logs Action username, password, iam_access_token, iam_apikey, iam_url, headers, headers[X-Watson-Learning-Opt-Out], url, filter, sort, page_limit, cursor List log events in all workspaces.
Because of their known behavior, they are often used in dialogs to force a parent node to evaluate a specific child node in succession. To prevent breaking existing dialog flow logic, digression are not allowed in this case. Before you can enable digressions away from such a node, you must change the child node's condition to something else.

<-- <ul> -->

* If the node is configured to jump to another node or skip user input after it is processed

<-- </ul> -->

The final step section of a node specifies what should happen after the node is processed. When the dialog is configured to jump directly to another node, it is often to ensure that a specific sequence is followed. And when the node is configured to skip user input, it is equivalent to forcing the dialog to process the first child node after the current node in succession. To prevent breaking existing dialog flow logic, digressions are not allowed in either of these cases. Before you can enable digressions away from this node, you must change what is specified in the final step section.
<-- </ul> --><-- </section "id="section-dialog-runtime-digression-prereqs" "> --><-- <section "id="section-dialog-runtime-enable-digressions" "> --> Customizing digressions You do not define the start and end of a digression. The user is entirely in control of the digression flow at run time. You only specify how each node should or should not participate in a user-led digression. For each node, you configure whether:<-- <ul> --> * a digression can start from and leave the node * a digression that starts elsewhere can target and enter the node * a digression that starts elsewhere and enters the node must return to the interrupted dialog flow after the current dialog flow is completed<-- </ul> -->To change the digression behavior for an individual node, complete the following steps:<-- <ol> -->1. Click the node to open its edit view.2.
The following example shows how you might send a response containing multiple response types (text, an image, and clickable options):

{
"output": {
"generic":[
{
"response_type": "text",
"values":
{
"text": "Here are your nearest stores."
}
]
},
{
"response_type": "image",
"source": "https://example.com/image.jpg",
"title": "Example image",
"description": "Some description for the image."
},
{
"response_type": "option",
"title": "Click on one of the following",
"options":
{
"label": "Location 1",
"value": {
"input": {
"text": "Location 1"
}
}
},
{
"label": "Location 2",
"value": {
"input": {
"text": "Location 2"
}
}
},
{
"label": "Location 3",
"value": {
"input": {
"text": "Location 3"
}
}
}
]
}
]
}
}
Show more

For more information about how to specify each supported response type using JSON objects, see [Response types](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-jsondialog-responses-json-response-types).

If you are using an integration, the response is converted at run time into the format expected by the channel. If the response contains multiple media types or attachments, the generic response is converted into a series of separate message payloads as needed. These are sent to the channel in separate messages.

When a response is split into multiple messages, the integration sends these messages to the channel in sequence.
The following example shows how the output object is represented in the dialog JSON editor:

{
"output": {
"generic": [
{
"values":
{
"text": "This is my response text."
}
],
"response_type": "text",
"selection_policy": "sequential"
}
]
}
}



In the resulting API /message response, the text response is formatted as follows:

{
"text": "This is my response text.",
"response_type": "text"
}

The following output object JSON format is supported for backwards compatibility. With the introduction of rich response types, the output.text structure was augmented with the output.generic structure to facilitate supporting other types of responses in addition to text. Use the new format when you create new nodes to give yourself more flexibility, because you can subsequently change the response type, if needed.

{
"output": {
"text": {
"values": [
"This is my response text."
]
}
}
}

There are response types other than a text response that you can define. See [Responses](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-overviewdialog-overview-responses) for more details.

You can learn more about the /message API call from the [API reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2).



 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.
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. See [Responses](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-builddialog-overview-responses) for more information.



You can think of the node as having an if/then construction: if this condition is true, then return this response.

For example, the following node is triggered if the natural language processing function of your assistant determines that the user input contains the cupcake-menu intent. As a result of the node being triggered, your assistant responds with an appropriate answer.

![Shows the user asking about cupcake flavors. the If condition is #cupcake-menu and the Then response is a list of cupcake flavors.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/node1-simple.png)

A single node with one condition and response can handle simple user requests. But, more often than not, users have more sophisticated questions or want help with more complex tasks. You can add child nodes that ask the user to provide any additional information that your assistant needs.

![Shows that the first node in the dialog asks which type of cupcake the user wants, gluten-free or regular, and has two child nodes that provide a different response depending on the user's answer.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/node1-children.png)
* Nodes with slots: Choose whether the user is only allowed to digress away if they will return to the current node by selecting the Only digress from slots to nodes that allow returns checkbox.

When selected, as the dialog looks for a node to answer the user's unrelated question, it ignores any root nodes that are not configured to return after the digression. Select this checkbox if you want to prevent users from being able to permanently leave the node before they have finished filling the required slots.







 Digressions into this node 

You can make the following choices about how digressions into a node behave:



* Prevent users from being able to digress into the node. See [Disabling digressions into a root node](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-runtimedialog-runtime-disable-digressions) for more details.
* When digressions into the node are enabled, choose whether the dialog must go back to the dialog flow that it digressed away from. When selected, after the current node's branch is done being processed, the dialog flow goes back to the interrupted node. To make the dialog return afterwards, select Return after digression.



The following image shows you how digressions into the #cuisine node (shown in the earlier illustration) are configured.

![Shows the digressions away settings from a node with slots.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/digress-into-cuisine-full.png)



3. Click Apply.
4. Use the Try it out pane to test the digression behavior.

Again, you cannot define the start and end of a digression. The user controls where and when digressions happen. You can only apply settings that determine how a single node participates in one. Because digressions are so unpredictable, it is hard to know how your configuration decisions will impact the overall conversation.
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).



 Implementing responses 

A dialog node can respond to users with a response that includes text, images, or interactive elements such as clickable options. If you are building your own client application, you must implement the correct display of all response types returned by your dialog. (For more information about dialog responses, see [Responses](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-responses)).



 Response output format 

By default, responses from a dialog node are specified in the output.generic object in the response JSON returned from the /message API. The generic object contains an array of up to 5 response elements that are intended for any channel. The following JSON example shows a response that includes text and an image:

{
"output": {
"generic": [
{
"response_type": "text",
"text": "OK, here's a picture of a dog."
},
{
"response_type": "image",
"source": "http://example.com/dog.jpg"
}
],
"text" : ["OK, here's a picture of a dog."]
},
"user_id": "faf4a112-f09f-4a95-a0be-43c496e6ac9a"
}
Show more

As this example shows, the text response (OK, here's a picture of a dog.) is also returned in the output.text array. This is included for backward compatibility for older applications that do not support the output.generic format.

It is the reponsibility of your client application to handle all response types appropriately. In this case, your application would need to display the specified text and image to the user.





 Response types
[Improving a dialog node with slots](https://cloud.ibm.com/docs/assistant?topic=assistant-tutorial-slots-complex)Improving a dialog node with slots

In this tutorial, you will enhance a simple node with slots that collects the information necessary to make a restaurant reservation.

Classic Watson Assistant



* 2 hours
* 2021-01-15



[Adding a node with slots to a dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-tutorial-slots)Adding a node with slots to a dialog

In this tutorial, you will add slots to a dialog node to collect multiple pieces of information from a user within a single node. The node you create will collect the information that is needed to make a restaurant reservation.

Classic Watson Assistant



* 30 minutes
* 2021-04-08



[Building a complex dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-tutorial)Building a complex dialog

In this tutorial, you will use the Watson Assistant service to create a dialog for an assistant that helps users with inquiries about a fictitious restaurant called Truck Stop Gourmand.

Classic Watson Assistant



* 2 hours
* 2022-02-23



[Getting started with Watson Discovery](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-getting-started)Getting started with Watson Discovery

In this tutorial, we introduce IBM Watson® Discovery and walk you through the Discovery sample project. Exploring the sample project is a great way to tour and try out some of the product's features.

Discovery v2



* 20 minutes
* 2023-03-31



[Power your assistant with answers from web resources](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-tutorial-assistant-fred)Power your assistant with answers from web resources

In this tutorial, you will use the Watson Discovery and Watson Assistant services to create a virtual assistant that can answer questions about the latest research from the US Federal Reserve.
For example, the initial response might be, We offer cupcakes in all shapes and sizes. Which menu do you want to see: gluten-free, dairy-free, or regular? If the user changes subjects at this point, you might want the dialog to return so the user can pick a menu type and get the information they wanted.
* Nodes with slots: Choose whether you want to allow users to digress away from the node before all of the slots are filled. Set the Allow digressions away while slot filling toggle to Yes to enable digressions away.

If enabled, when the conversation returns from the digression, the prompt for the next unfilled slot is displayed to encourage the user to continue providing information. If disabled, then any inputs that the user submits which do not contain a value that can fill a slot are ignored. However, you can address unsolicited questions that you anticipate your users might ask while they interact with the node by defining slot handlers. See [Adding slots](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-slotsdialog-slots-add) for more information.

The following image shows you how digressions away from the #reservation node with slots (shown in the earlier illustration) are configured.

![Shows the digressions away settings from a node with slots.](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/digress-away-slots-full.png)
* Nodes with slots: Choose whether the user is only allowed to digress away if they will return to the current node by selecting the Only digress from slots to nodes that allow returns checkbox.

When selected, as the dialog looks for a node to answer the user's unrelated question, it ignores any root nodes that are not configured to return after the digression. Select this checkbox if you want to prevent users from being able to permanently leave the node before they have finished filling the required slots.







 Digressions into this node
This is the default type.



* For nodes of type slot that have the same parent node, the sibling order (specified by the previous_sibling property) reflects the order in which the slots will be processed.
* A node of type slot must have a parent node of type frame.
* A node of type frame must have at least one child node of type slot.
* A node of type response_condition must have a parent node of type standard or frame.
* Nodes of type response_condition and event_handler cannot have children.
* A node of type event_handler must also have an event_name property that contains one of the following values to identify the type of node event:



* filled: Defines what to do if the user provides a value that meets the condition specified in the Check for field of a slot, and the slot is filled in. A handler with this name is only present if a Found condition is defined for the slot.
* focus: Defines the question to show to prompt the user to provide the information needed by the slot. A handler with this name is only present if the slot is required.
* generic: Defines a condition to watch for that can address unrelated questions that users might ask while filling a slot or node with slots.
* input: Updates the message context to include a context variable with the value that is collected from the user to fill the slot. A handler with this name must be present for each slot in the frame node.
* nomatch: Defines what to do if the user's response to the slot prompt does not contain a valid value. A handler with this name is only present if a Not found condition is defined for the slot.



The following diagram illustrates where in the tool user interface you define the code that is triggered for each named event.

![UI location where the code that is triggered by named event handlers is authored](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/api-event-handlers.png)
* A node of type event_handler with an event_name of generic can have a parent of type slot or frame.
* Nodes with slots: Choose whether the user is only allowed to digress away if they will return to the current node by selecting the Only digress from slots to nodes that allow returns checkbox.

When selected, as the dialog looks for a node to answer the user's unrelated question, it ignores any root nodes that are not configured to return after the digression. Select this checkbox if you want to prevent users from being able to permanently leave the node before they have finished filling the required slots.

<-- </ul> -->

Digressions into this node

You can make the following choices about how digressions into a node behave:

<-- <ul> -->

* Prevent users from being able to digress into the node. See Disabling digressions into a root node]]!
Shows the digressions away settings from a node with slots.Shows the digressions away settings from a node with slots_. 1] !
Shows two dialogs, one that sets the digressions away from the reservation slots node and one that sets the digression into the cuisine node.Shows two dialogs_ one that sets the digressions away from the reservation slots node and one that sets the digression into the cuisine node_.] ! ! ! for more details.
* When digressions into the node are enabled, choose whether the dialog must go back to the dialog flow that it digressed away from. When selected, after the current node's branch is done being processed, the dialog flow goes back to the interrupted node. To make the dialog return afterwards, select Return after digression.

<-- </ul> -->

The following image shows you how digressions into the #cuisine node (shown in the earlier illustration) are configured.

!]3. Click Apply.4. Use the "Try it out" pane to test the digression behavior.
Again, you cannot define the start and end of a digression. The user controls where and when digressions happen. You can only apply settings that determine how a single node participates in one.
For more information about how to specify each supported response type using JSON objects, see [Response types](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-jsondialog-responses-json-response-types).

If you are using an integration, the response is converted at run time into the format expected by the channel. If the response contains multiple media types or attachments, the generic response is converted into a series of separate message payloads as needed. These are sent to the channel in separate messages.

When a response is split into multiple messages, the integration sends these messages to the channel in sequence. It is the responsibility of the channel to deliver these messages to the end user; this can be affected by network or server issues.

If you are building your own client application, your app must implement each response type as appropriate. For more information, see [Implementing responses](https://cloud.ibm.com/docs/assistant?topic=assistant-api-dialog-responses).





 Targeting specific integrations 

If you plan to use integrations to deploy your assistant to multiple channels, you might want to send different responses to different integrations. The channels property of the generic response object provides a way to do this.

This mechanism is useful if your dialog flow does not change based on the integration in use, and if you cannot know in advance what integration the response will be sent to at run time. By using channels, you can define a single dialog node that supports all integrations, while still customizing the output for each channel. For example, you might want to customize the text formatting, or even send different response types, based on what the channel supports.

Using channels is particularly useful in conjunction with the channel_transfer response type. Because the message output is processed both by the channel initiating the transfer and by the target channel, you can use channels to define responses that will only be displayed by one or the other. (For more information, and an example, see [Channel transfer](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-jsondialog-responses-json-channel-transfer).)