Building a conversational flow

Condition artifacts

You can use one or more of the following artifacts in any combination to define a condition:

• Context variable: The node is used if the context variable expression that you specify is true. Use the syntax, $variable_name:value or $variable_name == 'value'.

  For node conditions, this artifact type is typically used with an AND or OR operator and another condition value. That's because something in the user input must trigger the node; the context variable value being matched alone is not enough to trigger it. If the user input object sets the context variable value somehow, for example, then the node is triggered.

  Do not define a node condition based on the value of a context variable in the same dialog node in which you set the context variable value.

  For response conditions, this artifact type can be used alone. You can change the response based on a specific context variable value. For example, $city:Boston checks whether the $city context variable contains the value, Boston. If so, the response is returned.

  For more information about context variables, see Context variables.

• Entity: The node is used when any value or synonym for the entity is recognized in the user input. Use the syntax, @entity_name. For example, @city checks whether any of the city names that are defined for the @city entity were detected in the user input. If so, the node or response is processed.

  Consider creating a peer node to handle the case where none of the entity's values or synonyms are recognized.

  For more information about entities, see Defining entities.

• Entity value: The node is used if the entity value is detected in the user input. Use the syntax, @entity_name:value and specify a defined value for the entity, not a synonym. For example: @city:Boston checks whether the specific city name, Boston, was detected in the user input.

  If you check for the presence of the entity, without specifying a particular value for it, in a peer node, be sure to position this node (which checks for a particular entity value) before the peer node that checks only for the presence of the entity. Otherwise, this node will never be evaluated.

  If the entity is a pattern entity with capture groups, then you can check for a certain group value match. For example, you can use the syntax: @us_phone.groups[1] == '617' See Storing and recognizing pattern entity groups in input 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.

• 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

Condition syntax details

Use one of these syntax options to create valid expressions in conditions:

• Shorthand notations to refer to intents, entities, and context variables. See Accessing and evaluating objects.

• Spring Expression (SpEL) language, which is an expression language that supports querying and manipulating an object graph at run time. See Spring Expression Language (SpEL) language for more information.

You can use regular expressions to check for values to condition against. To find a matching string, for example, you can use the String.find method. See Methods for more details.

Simple text response

If you want to provide a text response, simply enter the text that you want your assistant to display to the user.

To include a context variable value in the response, use the syntax $variable_name to specify it. See Context variables for more information. For example, if you know that the $user context variable is set to the current user's name before a node is processed, then you can refer to it in the text response of the node like this:

Hello $user

If the current user's name is Norman, then the response that is displayed to Norman is Hello Norman.

If you include one of these special characters in a text response, escape it by adding a backslash (\) in front of it. If you are using the JSON editor, you need to use two backslashes to escape (\\). Escaping the character prevents your assistant from misinterpreting it as being one of the following artifact types:

To include a hypertext link that is rendered in the Try it out pane, you can use HTML syntax. For example: Contact us at <a href="https://www.ibm.com">ibm.com</a>. (Do not try to escape the quotations mark with a backslash \", for example.)

Hi.
How are you today?

Rich responses

You can return responses with multimedia or interactive elements such as images or clickable buttons to simplify the interaction model of your application and enhance the user experience.

In addition to the default response type of Text, for which you specify the text to return to the user as a response, the following response types are supported:

• Connect to human agent: The dialog calls a service that you designate, typically a service that manages human agent support ticket queues, to pass off the conversation to a person. You can optionally include a message that summarizes the user's issue to be provided to the human agent. It is the responsibility of the external service to display a message that is shown to the user that explains that the conversation is being transferred. The dialog does not manage that communication itself. The dialog transfer does not occur when you are testing nodes with this response type in the Try it out pane. You must access a node that uses this response type from a test deployment to see how your users will experience it.

• Image: Embeds an image into the response. The source image file must be hosted somewhere and have a URL that you can use to reference it. It cannot be a file that is stored in a directory that is not publicly accessible.

• Option: Adds a list of one or more options. When a user clicks one of the options, an associated user input value is sent to your assistant. How options are rendered can differ depending on where you deploy the dialog. For example, in one integration channel the options might be displayed as clickable buttons, but in another they might be displayed as a dropdown list.

• Pause: Forces the application to wait for a specified number of milliseconds before continuing with processing. You can choose to show an indicator that the dialog is working on typing a response. Use this response type if you need to perform an action that might take some time. For example, a parent node makes a Cloud Function call and displays the result in a child node. You could use this response type as the response for the parent node to give the programmatic call time to complete, and then jump to the child node to show the result. This response type does not render in the Try it out pane. You must access a node that uses this response type from a test deployment to see how your users will experience it.

• Search skill: Searches an external data source for relevant information to return to the user. The data source that is searched is a Discovery service data collection that you configure when you add a search skill to the assistant that uses this dialog skill. For more information, see Creating a search skill.

Conditional responses

A single dialog node can provide different responses, each one triggered by a different condition. Use this approach to address multiple scenarios in a single node.

The node still has a main condition, which is the condition for using the node and processing the conditions and responses that it contains.

In this example, your assistant uses information that it collected earlier about the user's location to tailor its response, and provide information about the store nearest the user. See Context variables for more information about how to store information collected from the user.

This single node now provides the equivalent function of four separate nodes.

To add conditional responses to a node, complete the following steps:

1. Click Customize, and then click the Multiple responses toggle to turn it On.

   The node response section changes to show a pair of condition and response fields. You can add a condition and a response into them.

2. To customize a response further, click the Edit response icon next to the response.

   You must open the response for editing to complete the following tasks:

   • Update context. To change the value of a context variable when the response is triggered, specify the context value in the context editor. You update context for each individual conditional response; there is no common context editor or JSON editor for all conditional responses.

   • Add rich responses. To add more than one text response or to add response types other than text responses to a single conditional response, you must open the edit response view.

   • Configure a jump. To instruct your assistant to jump to a different node after this conditional response is processed, select Jump to from the And finally section of the response edit view. Identify the node that you want your assistant to process next. See Configuring the Jump to action for more information.

     A Jump to action that is configured for the node is not processed until all of the conditional responses are processed. Therefore, if a conditional response is configured to jump to another node, and the conditional response is triggered, then the jump configured for the node is never processed, and so does not occur.

3. Click Add response to add another conditional response.

The conditions within a node are evaluated in order, just as nodes are. Be sure that your conditional responses are listed in the correct order. If you need to change the order, select a condition and response pair and move it up or down in the list using the arrows that are displayed.

Configuring the Jump to action

If you choose to jump to another node, specify when the target node is processed by choosing one of the following options:

• Condition: If the statement targets the condition section of the selected dialog node, your assistant checks first whether the condition of the targeted node evaluates to true.

  • If the condition evaluates to true, the system processes the target node immediately.

  • If the condition does not evaluate to true, the system moves to the next sibling node of the target node to evaluate its condition, and repeats this process until it finds a dialog node with a condition that evaluates to true.

  • If the system processes all the siblings and none of the conditions evaluate to true, the basic fallback strategy is used, and the dialog evaluates the nodes at the base level of the dialog tree.

  Targeting the condition is useful for chaining the conditions of dialog nodes. For example, you might want to first check whether the input contains an intent, such as #turn_on, and if it does, you might want to check whether the input contains entities, such as @lights, @radio, or @wipers. Chaining conditions helps to structure larger dialog trees.

  Avoid choosing this option when configuring a jump-to from a conditional response that goes to a node situated before the current node in the dialog tree. Otherwise, you can create an infinite loop. If your assistant jumps to the earlier node and checks its condition, it is likely to return false because the same user input is being evaluated that triggered the current node last time through the dialog. Your assistant will go to the next sibling or back to root to check the conditions on those nodes, and will likely end up triggering this node again, which means the process will repeat itself.

• Response: If the statement targets the response section of the selected dialog node, it is run immediately. That is, the system does not evaluate the condition of the selected dialog node; it processes the response of the selected dialog node immediately.

  Targeting the response is useful for chaining several dialog nodes together. The response is processed as if the condition of this dialog node is true. If the selected dialog node has another Jump to action, that action is run immediately, too.

• Wait for user input: Waits for new input from the user, and then begins to process it from the node that you jump to. This option is useful if the source node asks a question, for example, and you want to jump to a separate node to process the user's answer to the question.