A guide variable enables your AI agent to pass information within the guide, send information to Architect Virtual Agent flows, and receive information from Architect Virtual Agent flows. For example, you can use references between steps in the guide and exchange data with Architect flows during the conversation, making the customer’s interaction more dynamic.

When creating variables, you can use optional validation controls to define how values are captured in guides. Once configured, the guide accepts only values that meet the specified criteria. Provide brief, high-level descriptions for variables and rely on validation settings to enforce constraints. If a participant submits a value outside the allowed criteria, the guide-based Virtual Agent responds with a message indicating the issue.

Create guide variables

1. Click Menu > Orchestration > AI Studio > Guides.
2. Open an existing guide or create a new one.
3. Open the Variables tab and click Create. The Create variable panel opens.
   Show meClick to expand

   

4. Under Create variable, follow these steps:
   1. In the Name field, enter a variable name.
      Note: The maximum length of a variable name is 80 characters.
   2. From the Data type list, select one of the following data types:
      • string: A standard text string. Data other than a number, integer, or Boolean must be captured through a string variable.
      • boolean: A Boolean can have only one of two values: true or false.
      • number: A number includes decimal values such as an amount of money.
      • integer: An integer is a whole number such as the number of people for a reservation.
      • date: A date value in a specified date format such as yyyy-mm-dd. 
      • list: An array of items paired with optional synonyms.
        Note: Ensure that the data type matches correctly with the intended values. This behavior improves the large language model (LLM) accuracy when identifying and gathering information.
   3. From the Availability list, select the appropriate direction of data transfer. 
      • Input: Use this direction to receive data from the Virtual Agent-enabled flow. 
      • Output: Use this direction to send data to the Virtual Agent-enabled flow.
      • Input & Output: Use this option to send data to or receive data from the Architect flow.
      • Guide only: Use this option to ensure that data is used exclusively within the guide.
        Note: For any information that you want to use within the guide, select any of the data direction options.
   4. In the Description text box, enter a description that is simple and clear.
   5. (Optional) Under Validation, configure the rules (conditions) that the system must evaluate before accepting a value. 
   6. If you chose list from the Data type list, configure the list options using these steps:
      1. Select one of the following list types:
         • Static List: Use this option to define the list of values and synonyms manually.
         • Dynamic List: Use this option to retrieve values through an existing data action.
      2. Under List values, set values manually for a static list or select the data action for a dynamic list.
         • For a static list, select whether the participant input must match exactly or partially using the Exact Match | Flexible Match toggle. Then, click Add value and add list values along with synonyms.
         • For a dynamic list, select an existing data action from the Data action list. Before selecting the Data Action, one must be created that returns an array of string values and, optionally, an array of arrays of string synonyms. The synonyms must be structured as an array of arrays, since each value can have multiple synonyms. If there is only one synonym per value, a single array can be returned for each entry.
5. Click Create. You can now use this variable in your guides.

Validation (optional)

The validation options in the Validation section enable you to apply rules and conditions to a variable. The validation parameters are optional and they vary depending on the selected data type.

Strings

You can configure the validation options for string variables using either the pre-existing rules or regular expressions. Rules and regex enable authors to enforce predefined criteria for user input. If a value fails validation, the system returns an error message and requires a valid input before proceeding from the Ask command. 

To add rule conditions, select Rules in the Rules | Regex toggle and click Add Rules. The following rule conditions are available:

To add regex, select Regex in the Rules | Regex toggle and click Add Regex. Then, enter your regular expression to validate the string values. You can combine multiple expressions. 

You can also test how your rules or regular expressions work by entering a sample string value in the Test field. 

Show meClick to expand

Numbers and integers

Set the minimum and maximum values that the variable must accept. Both the minimum and maximum values are optional.

Dates

Use the date validation options to indicate which dates and date formats that the system must allow. 

1. Select the allowed dates from the Capture list. The following options are available:
   • Any date: This option allows the date variable to accept any date.
   • Past dates only: This option allows the date variable to accept only specified past dates. You can define the rolling aggregate in the past such as refunds only valid for the last one year.
   • Future dates only: This option allows the date variable to accept only specified future dates. You can define a rolling aggregate in the future, such as limiting restaurant reservations to 30 days ahead.
   • Within a date range: This option allows you to select a date range that the variable must accept.
2. From the Store as list, select the allowed date format.

Use variables

1. Open an existing guide or create a new one.
2. In the Instructions tab, place your cursor where you want to insert a variable and type /. 
   A pop-up dialog box appears showing options to insert a data action or variable.
3. Select Variables. The dialog box now lists the available variables. 
4. Select the required variable. The editor emphasizes variables present in your guide with a gray background.
5. Click Save to save the guide or click Publish to publish the guide.
   Note: The maximum number of variables that you can have in a single guide is 50.