Conditions reference

This reference describes the syntax for using conditions in routes. When a condition evaluates to true, the associated route is called when the route is evaluated. This syntax allows from very simple to very complex expressions using parameter values, sentiment values, comparison operators, boolean operators, and functions.

The simplest condition is the boolean constant true, which forces a route to be called when it is evaluated. You can build more complex conditions which evaluate to true for cases like:

  • A parameter equals a specific value
  • A parameter is less than or greater than a specific value
  • A parameter is in a range of values
  • One parameter is greater than another parameter
  • A form has been completed
  • End-user sentiment is positive or negative
  • A probability from a random function

To set conditions in the console, see the handler documentation.

Comparison operators

The following comparison operators are supported:

  • HAS (:)
  • EQUALS (=)
  • NOT_EQUALS (!=)
  • LESS_THAN (<)
  • LESS_THAN_EQUALS (<=)
  • GREATER_THAN (>)
  • GREATER_THAN_EQUALS (>=)

Rules for comparison operators

  • The left hand side must be a parameter reference.
    $a = 5
    
  • The right hand side is type casted to the same type as the left hand side before comparing.
  • HAS (:) for anything other than strings is treated as EQUALS (=).

Support for strings

  • HAS (:) performs a substring search. If $a is set to "hello world", the following is true:
    $a : "hello"
    
  • When using strings on the right hand side, double quotes are needed if the string contains space. If $a is set to "hello world", the following is true:
    $a = "hello world"
    
  • LESS_THAN (<), LESS_THAN_EQUALS (<=), GREATER_THAN (>), and GREATER_THAN_EQUALS (>=) compare lexicographically. If $a is set to "abc", the following is true:
    $a > "aaa"
    

Boolean operators

Conjunction (AND)

For the AND operator, expressions are evaluated iteratively, and the evaluation is short-circuited if any expression evaluates to false. Example:

$a > 0 AND $a < 100

Disjunction (OR)

For the OR operator, expressions are evaluated iteratively, and the evaluation is short-circuited if any expression evaluates to true. Example:

$a = 0 OR $a > 5

Negation (NOT)

For the NOT operator, the expression is negated. Example:

NOT $a <= 0

Rules for boolean operators

  • The boolean operators must be uppercase.
  • The boolean operators must not be part of a quoted string.

Boolean constants

The following boolean constants are defined:

true
false

To force a route to be called upon evaluation, use the following condition:

true

Functions

The following built-in functions can be used in condition expressions.

Rand

You can use the rand function to generate a random floating point number in the range [0,1). For example, there is a 10% probability that the following condition will be true:

$sys.func.rand() < 0.1

Compound expressions

You can use boolean operators and comparison operators to form compound expressions. Parentheses may be used to make the logic clearer or change the precedence. For example:

(NOT ($a > 1 AND $b < 100)) OR $c = 50

If you are not using parenthesis, you cannot use both OR and AND operators in a compound expression:

$a=1 AND $b=2 AND $c=3  // VALID
$a=1 OR $b=2 OR $c=3    // VALID
$a=1 OR $b=2 AND $c=3   // INVALID
($a=1 OR $b=2) AND $c=3 // VALID

Parameter references

The parameter references you can use in conditions are found in the parameters guide. The remainder of this section provides examples for using parameters in conditions.

To check whether the current page's form is filled, use the following condition:

$page.params.status = "FINAL"

To check whether a particular form parameter was filled for the end-user's previous conversational turn, use the following condition:

$page.params.parameter-id.status = "UPDATED"

To check that a numerical session parameter is between the values 1 and 10, use the following condition:

$session.params.parameter-id >= 1 AND $session.params.parameter-id <= 10

To check that the second value of a list session parameter is equal to "hello", use the following condition:

$session.params.parameter-id[1] = "hello"

Sentiment references

When defining a condition, you can use certain sentiment references to form your condition. This allows your agent to tailor responses based on sentiment. The following sentiment references are supported:

Reference Type Description
$request.sentiment.score Number Sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment).
$request.sentiment.magnitude Number Indicates the overall strength of emotion (both positive and negative) between 0.0 and +inf. Unlike score, magnitude is not normalized; each expression of emotion within the end-user input (both positive and negative) contributes to the input's magnitude. Longer inputs may have greater magnitudes.
$request.sentiment.succeeded Boolean True if sentiment analysis succeeded, false otherwise.

Example conditions that use sentiment:

$request.sentiment.score < 0
$request.sentiment.score > 0
$request.sentiment.magnitude > 3.6
$request.sentiment.succeeded = true
$request.sentiment.succeeded = false