Personalizing the dialog with context

Passing context from the application

Pass information from the application to the dialog by setting a context variable and passing the context variable to the dialog.

For example, your application can set a $time_of_day context variable, and pass it to the dialog which can use the information to tailor the greeting it displays to the user.

In this example, the dialog knows that the application sets the variable to one of these values: morning, afternoon, or evening. It can check for each value, and depending on which value is present, return the appropriate greeting. If the variable is not passed or has a value that does not match one of the expected values, then a more generic greeting is displayed to the user.

Passing context from node to node

The dialog can also add context variables to pass information from one node to another or to update the values of context variables. As the dialog asks for and gets information from the user, it can keep track of the information and reference it later in the conversation.

For example, in one node you might ask users for their name, and in a later node address them by name.

In this example, the system entity @name is used to extract the user's name from the input if the user provides one. In the JSON editor, the username context variable is defined and set to the @name value. In a subsequent node, the $username context variable is included in the response to address the user by name.

Defining a context variable

Define a context variable by adding the variable name to the Variable field and adding a default value for it to the Value field in the node's edit view.

1. Click to open the dialog node to which you want to add a context variable.

2. Go to the Assistant responds section and click the menu icon .

   If you're using multiple conditioned responses, you must click the Customize response icon to see the menu that is associated with the response.

3. Click Open context editor.

   

4. Add the variable name and value pair to the Variable and Value fields.

   • The name can contain any upper- and lowercase alphabetic characters, numeric characters (0-9), and underscores.

     You can include other characters, such as periods and hyphens, in the name. However, if you do, then you must specify the shorthand syntax $(variable-name) every time you subsequently reference the variable. See Expressions for accessing objects for more details.

   • The value can be any supported JSON type, such as a simple string variable, a number, a JSON array, or a JSON object.

The following table shows some examples of how to define name and value pairs for different types of values:

To subsequently refer to these context variables, use the syntax $name where name is the name of the context variable that you defined.

For example, you might specify the following expression as the dialog response:

The customer, $age-year-old <? $full_name.first ?>, wants a pizza with <? $toppings_array.join(' and ') ?>, and then $dessert.

The resulting output is displayed as follows:

The customer, 18-year-old John, wants a pizza with onions and olives, and then cake.

You can use the JSON editor to define context variables also. You might prefer to use the JSON editor if you want to add a complex expression as the variable value. See Context variables in the JSON editor for more details.

Common context variable tasks

To store the entire string that was provided by the user as input, use input.text:

For example, the user input is, I want to order a device. If the node response is, You said: $repeat, then the response would be displayed as, You said: I want to order a device.

To store the value of an entity in a context variable, use this syntax:

For example, the user input is, I want to go to Paris. If your @place entity recognizes Paris, then your assistant saves Paris in the $place context variable.

To store the value of a string that you extract from the user's input, you can include a SpEL expression that uses the extract method to apply a regular expression to the user input. The following expression extracts a number from the user input, and saves it to the $number context variable.

To store the value of a pattern entity, append .literal to the entity name. Using this syntax ensures that the exact span of text from user input that matched the specified pattern is stored in the variable.

For example, the user input is Contact me at joe@example.com. Your entity named @email recognizes the name@domain.com email format. By configuring the context variable to store @email.literal, you indicate that you want to store the part of the input that matched the pattern. If you omit the .literal property from the value expression, then the entity value name that you specified for the pattern is returned instead of the segment of user input that matched the pattern.

Many of these value examples use methods to capture different parts of the user input. For more information about the methods available for you to use, see Expression language methods.

Deleting a context variable

To delete a context variable, set the variable to null.

Alternatively you can delete the context variable in your application logic. For information about how to remove the variable entirely, see Deleting a context variable in JSON.

Updating a context variable value

To update a context variable's value, define a context variable with the same name as the previous context variable, but this time, specify a different value for it.

When more than one node sets the value of the same context variable, the value for the context variable can change over the course of a conversation with a user. Which value is applied at any given time depends on which node is being triggered by the user in the course of the conversation. The value specified for the context variable in the last node that is processed overwrites any values that were set for the variable by nodes that were processed previously.

For information about how to update the value of a context variable when the value is a JSON object or JSON array data type, see Updating a context variable value in JSON

How context variables are processed

Where you define the context variable matters. The context variable is not created and set to the value that you specify for it until your assistant processes the part of the dialog node where you defined the context variable. In most cases, you define the context variable as part of the node response. When you do so, the context variable is created and given the specified value when your assistant returns the node response.

For a node with conditional responses, the context variable is created and set when the condition for a specific response is met and that response is processed. For example, if you define a context variable for conditional response #1 and your assistant processes conditional response #2 only, then the context variable that you defined for conditional response #1 is not created and set.

For information about where to add context variables that you want your assistant to create and set as a user interacts with a node with slots, see Adding context variables to a node with slots.

Order of operation

When you define multiple variables to be processed together, the order in which you define them does not determine the order in which they are evaluated by your assistant. Your assistant evaluates the variables in random order. Do not set a value in the first context variable in the list and expect to be able to use it in the second variable in the list, because there is no guarantee that the first context variable will be executed before the second one. For example, do not use two context variables to implement logic that checks whether the user input contains the word Yes in it.

Instead, use a slightly more complex expression to avoid having to rely on the value of the first variable in your list (user_input) being evaluated before the second variable (contains_yes) is evaluated.

Adding context variables to a node with slots

For more information about slots, see Gathering information with slots.

1. Open the node with slots in the edit view.

   • To add a context variable that is processed after a response condition for a slot is met, perform the following steps:

     1. Click the Edit slot icon .
     2. Click the Options icon , and then select Enable conditional responses.
     3. Click the Edit response icon next to the response with which you want to associate the context variable.
     4. Click the Options icon in the response section, and then click Open context editor.
     5. Add the variable name and value pair to the Variable and Value fields.

     

   • To add a context variable that is set or updated after a slot condition is met, complete the following steps:

     1. Click the Edit slot icon .

     2. From the Options menu in the Configure slot view header, click Open JSON editor.

     3. Add the variable name and value pair in JSON format.

        {
          "time_of_day": "morning"
        }
        

     There is currently no way to use the context editor to define context variables that are set during this phase of dialog node evaluation. You must use the JSON editor instead. For more information about using the JSON editor, see Context variables in the JSON editor.

     

Deleting a context variable in JSON

To delete a context variable, set the variable to null.

{
  "context": {
    "order_form": null
  }
}

If you want to remove all trace of the context variable, you can use the JSONObject.remove(string) method to delete it from the context object. However, you must use a variable to perform the removal. Define the new variable in the message output so it will not be saved beyond the current call.

{
  "output": {
    "text" : {},
    "deleted_variable" : "<? context.remove('order_form') ?>"
  }
}

Alternatively you can delete the context variable in your application logic.

Updating a context variable value in JSON

In general, if a node sets the value of a context variable that is already set, then the previous value is overwritten by the new value.

{
  "context": {
    "complex_object": {
      "user_firstname" : "Paul",
      "user_lastname" : "Pan",
      "has_card" : false
    }
  }
}

{
  "complex_object": {
    "user_firstname": "Peter",
    "has_card": true
  }
}

{
  "complex_object": {
    "user_firstname": "Peter",
    "user_lastname": "Pan",
    "has_card": true
  }
}

Setting one context variable equal to another

When you set one context variable equal to another context variable, you define a pointer from one to the other. If the value of one of the variables subsequently changes, then the value of the other variable is changed also.

For example, if you specify a context variable as follows, then when the value of either $var1 or $var2 subsequently changes, the value of the other changes too.

Do not set one variable equal to another to capture a point in time value. When dealing with arrays, for example, if you want to capture an array value stored in a context variable at a certain point in the dialog to save it for later use, you can create a new variable based on the current value of the variable instead.

For example, to create a copy of the values of an array at a certain point of the dialog flow, add a new array that is populated with the values for the existing array. To do so, you can use the following syntax:

{
"context": {
   "var2": "<? output.var2?:new JsonArray().append($var1) ?>"
 }
 }