---
name: watson-assistant-api-dialog-modify
title: Modifying a dialog by using the API
description: The REST API supports modifying your dialog programmatically. You can use the `/dialog_nodes` API to create, delete, or modify dialog nodes.
last-updated: 2023-10-24
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/watson-assistant?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Modifying a dialog by using the API
{: #api-dialog-modify}

The REST API supports modifying your dialog programmatically. You can use the `/dialog_nodes` API to create, delete, or modify dialog nodes.

A dialog is a tree of interconnected nodes, and that it must conform to certain rules to be valid. Any change that you make to a dialog node might have cascading effects on other nodes, or on the structure of your dialog. Before you use the `/dialog_nodes` API to modify your dialog, make sure you understand how your changes affect the rest of the dialog. You can make a backup copy of the current dialog For more information, see [Backing up and restoring data](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-admin-backup-restore&format=markdown).

A valid dialog always satisfies the following criteria:

- Each dialog node has a unique ID (the `dialog_node` property).
- A child node is aware of its parent node (the `parent` property). However, a parent node is not aware of its children.
- A node is aware of its immediate previous sibling, if any (the `previous_sibling` property). All siblings that share the parent form a linked list, with each node pointing to the previous node.
- Only one child of a parent can be the first sibling (meaning that its `previous_sibling` is null).
- A node cannot point to a previous sibling that is a child of a different parent.
- Two nodes cannot point to the same previous sibling.
- A node can specify another node that is to be run next (the `next_step` property).
- A node cannot be its own parent or its own sibling.
- A node must have a type property that contains one of the following values. If no type property is specified, then the type is `standard`.

   -  `event_handler`: A handler that is defined for a frame node or an individual slot node.

    From the tool, you can define a frame node handler by clicking the **Manage handlers** link from a node with slots. (The tool user interface does not expose the slot-level event handler, but you can define one through the API.)

   -  `frame`: A node with one or more child nodes of type `slot`. Any child slot nodes that are required must be filled before the service can exit the frame node.

    The frame node type is represented as a node with slots in the tool. The node that contains the slots is represented as a node of type=`frame`. It is the parent node to each slot, which is represented as a child node of type `slot`.

   -  `response_condition`: A conditional response.

    In the tool, you can add one or more conditional responses to a node. Each conditional response that you define is represented in the underlying JSON as an individual node of type=`response_condition`.

   -  `slot`: A child node of a node of type `frame`.

    This node type is represented in the tool as being one of multiple slots that are added to a single node. That single node is represented in the JSON as a parent node of type `frame`.

   -  `standard`: A typical dialog 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 are 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 that is specified in the *Check for* field of a slot, and the slot is filled. A handler with this name is only present if a Found condition is defined for the slot.
   -  `focus`: Defines the question to show that prompts 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 that 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](images/api-event-handlers.png){: caption="Event handlers" caption-side="bottom"}

- A node of type `event_handler` with an event_name of `generic` can have a parent of type `slot` or `frame`.
- A node of type `event_handler` with an event_name of `focus`, `input`, `filled`, or `nomatch` must have a parent of type `slot`.
- If more than one event_handler with the same event_name is associated with the same parent node, then the order of the siblings is the order in which the event handlers are run.
- For `event_handler` nodes with the same parent slot node, the order of execution is the same regardless of the placement of the node definitions. The events are triggered in this order by event_name:

   1. focus
   1. input
   1. filled
   1. generic*
   1. nomatch

   *If an `event_handler` with the event_name `generic` is defined for this slot or for the parent frame, then it is run between the filled and nomatch event_handler nodes.

The following examples show how various modifications might cause cascading changes.

## Creating a node
{: #api-dialog-modify-create-node}

Consider the following simple dialog tree:

![Example dialog](images/dialog_api_1.png){: caption="Example dialog" caption-side="bottom"}

We can create a new node by making a POST request to /dialog_nodes with the following body:

```json
{
  "dialog_node": "node_8"
}
```

The dialog now looks like this:

![Example dialog 2](images/dialog_api_2.png){: caption="Example dialog 2" caption-side="bottom"}

Because **node_8** was created without specifying a value for `parent` or `previous_sibling`, it is now the first node in the dialog. In addition to creating **node_8**, the service also modified **node_1** so that its `previous_sibling` property points to the new node.

You can create a node somewhere else in the dialog by specifying the parent and previous sibling:

```json
{
  "dialog_node": "node_9",
  "parent": "node_2",
  "previous_sibling": "node_5"
}
```
{: codeblock}

The values that you specify for `parent` and `previous_node` must be valid:

- Both values must refer to existing nodes.
- The specified parent must be the same as the parent of the previous sibling (or `null`, if the previous sibling has no parent).
- The parent cannot be a node of type `response_condition` or `event_handler`.

The resulting dialog looks like this:

![Example dialog 3](images/dialog_api_3.png){: caption="Example dialog 3" caption-side="bottom"}

In addition to creating **node_9**, the service automatically updates the `previous_sibling` property of *node_6* so that it points to the new node.

## Moving a node to a different parent
{: #api-dialog-modify-change-parent}

Move **node_5** to a different parent by using the POST `/dialog_nodes/node_5` method with the following body:

```json
{
  "parent": "node_1"
}
```
{: codeblock}

The specified value for `parent` must be valid:
- It must refer to an existing node.
- It must not refer to the node that is modified (a node cannot be its own parent).
- It must not refer to a descendant of the node that is modified.
- It must not refer to a node of type `response_condition` or `event_handler`.

This results in the following changed structure:

![Example dialog 4](images/dialog_api_4.png){: caption="Example dialog 4" caption-side="bottom"}

Several things happened here:
- When **node_5** moved to its new parent, **node_7** went with it (because the `parent` value for **node_7** did not change). When you move a node, all descendants of that node stay with it.
- Because we did not specify a `previous_sibling` value for **node_5**, it is now the first sibling under **node_1**.
- The `previous_sibling` property of **node_4** was updated to `node_5`.
- The `previous_sibling` property of **node_9** was updated to `null` because it is now the first sibling under **node_2**.

## Resequencing siblings
{: #api-dialog-modify-change-sibling}

Now set **node_5** as the second sibling instead of the first by using the `POST /dialog_nodes/node_5` method with the following body:

```json
{
  "previous_sibling": "node_4"
}
```
{: codeblock}

When you modify `previous_sibling`, the new value must be valid:
- It must refer to an existing node
- It must not refer to the node that is modified (a node cannot be its own sibling)
- It must refer to a child of the same parent (all siblings must have the same parent)

The structure changes as follows:

![Example dialog 5](images/dialog_api_5.png){: caption="Example dialog 5" caption-side="bottom"}

**Node_7** stays with its parent. In addition, **node_4** is modified so that its `previous_sibling` is `null` because it is now the first sibling.

## Deleting a node
{: #api-dialog-modify-delete-node}

Delete **node_1** by using the `DELETE /dialog_nodes/node_1` method.

The result is:

![Example dialog 6](images/dialog_api_6.png){: caption="Example dialog 6" caption-side="bottom"}

**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 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
{: #api-dialog-modify-rename-node}

Rename **node_2** using the `POST /dialog_nodes/node_2` method with the following body:

```json
{
  "dialog_node": "node_X"
}
```
{: codeblock}

![Example dialog 7](images/dialog_api_7.png){: caption="Example dialog 7" caption-side="bottom"}

The structure of the dialog didn't change, but 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.