Variables and conditionals
To build a user-friendly application that allows users to navigate freely, or create a personalized experience you will likely need to add some logic/conditional behavior to your app. This page covers how to set and use variables, and how to use conditionals based on what those variables are set to.
Variables
Variables are essential parts of any type of applications, and building dialog-based apps are no different. Narratory allows you to set custom variables but also comes with some built-in system variables.
System variables#
Narratory comes with a few handy variables set by the system that help you create personalized and engaging dialogs:
| Variable | Type | Description |
|---|---|---|
| sessionId | An unique string | An unique identifier generated by the Narratory system for the current session |
| platform | "google", "facebook", "slack", "kommunicate", "voximplant", unknown" and others | The platform that the user is using to interact with your app |
| user_text | string | The last utterance said by the user |
| bot_text | string | The last utterance said by the bot |
| lastTurnType | "narrative", "userInitiative", "bridge" | One of the three values to the left depending on if the previously executed BotTurn was part of the Narrative, the response to a user initiative or as a bridge |
| turnCount | A positive integer, starting at 0 | The amount of a times a turn is executed |
| retryCount | A positive integer, starting at 0 | The amount of fallbacks in a row. The retryCount resets whenever a non-fallback intent is matched |
Custom variables#
In addition to the above mentioned system variables, and variables set by captured Entities, as described in the NLU docs, you can also manually set custom variables that you can use for conditionals and API-requests.
Setting custom variables#
To set custom variables, you add a set input to any bot-turn by pressing the cog-wheel on the bot-turn as follows:
This sets the variable myVariable to the string value "some value".
Variable naming#
For good practise, we recommend variable names without spaces in either snake_case (i.e my_variable) or camelCase (i.e myVariable).
Variable types#
Your variables can be of any type, i.e. complex JSON structures are supported, but be aware that certain limitations exist for variables when you use them in utterances and conditionals.
Note: make sure your variables (entity parameter names and custom variables) have unique names, otherwise they will overwrite each other. This can of course be intentionally used as well, by manually overwriting values captures by entities and vice verse.
You can also set variables to the value of other already set variables, for example:
Here, our new variable is set to the value of the last user input (a system variable described above).
Conditionals
Conditionals consist of three parts, a variable that you want to check the condition for, an operator to determine what type of condition it is (equality, contains etc) and the comparator value - i.e the value you compare the variable with.
You can apply conditionals on two types of blocks:
- Bot turns
- Rich says
Types of conditionals#
Truthful check#
The first conditional block available checks if a variable is truthful or falsy. Truthful means that the variable is set to a non-null value - i.e NOT an empty string (""), an empty array ([]), the null-value (null) or not defined at all (undefined).
Comparison check#
The second type of conditional compares a variable (for example myVariable) with a value (for example the string "banana") or another variable with an operator that you select. The operator are for example "equals" and "contains".
Note: Comparison checks are ignoring case of the values, i.e a variable with value "Banana" will be considered equal to "banana" and "baNaNa".
Example of an equality check with a value:
Example of an equality check with another variable:
Conditionals on Bot turns#
To set a condition on a bot turn, you press the cog wheel on a Bot Turn block and drag out the cond block to the botTurn block as shown here:
You can then add a condition by using a condition block from the Logic category as shown below:
Conditions on Bot initiatives#
If you set a condition on a top level bot turn, i.e a bot initiative that is part of your Narrative, the bot will jump to the next bot initiative in your narrative if the conditions on a bot turn are not met. This is shown in the two captions above.
Conditions on followup bot turns#
You can also set conditions on bot turns that are followups to user turns, i.e the bot responses once the bot has understood something the user said. In this case, you can provide several bot turns to the user turn. Narratory will execute the first bot turn with a met condition (or without a condition), starting from the top.
In the above example, the bot has a followup question if the favorite color of the user is red, it jumps to another part of the narrative if the favorite color is green and otherwise just replies and then moves on.
Conditionals on Rich says#
Sometimes you want to only customize the output of the bot depending on some condition. This can be done by using the Rich text block and add a cond-input to it by pressing the cog-wheel on the block.
In this example, the bot replies differently depending on what favorite color the user states he/she likes, but the same turn is always executed - which in this case means the same webhook will be called.
Advanced conditionals#
You can combine any number of conditionals as shown below:
When you have more than one condition, every condition needs to be true for the turn to execute. In a more technical language, this means that the default behavior for several conditionals is AND. For more customized conditionals, you can use special blocks for the logical operators NOT, OR and AND:
A current limitation is that you cannot include more than one logical operator of the same type on the same level, for example two subsequent AND blocks or NOT blocks. This will be fixed in a coming update.