Expressions for accessing objects in dialog

You can write expressions that access objects and properties of objects by using the Spring Expression (SpEL) language. For more information, see Spring Expression Language (SpEL).

Evaluation syntax

To expand variable values inside other variables or invoke methods on properties and global objects, use the <? expression ?> expression syntax. For example:

Expanding a property

"output":{"text":"Your name is <? context.userName ?>"}

Invoking methods on properties of global objects
```
"context":{"email": "<? @email.literal ?>"}
```

Shorthand syntax

Learn how to quickly reference the following objects by using the SpEL shorthand syntax:

Context variables
Entities
Intents

Shorthand syntax for context variables

The following table shows examples of the shorthand syntax that you can use to write context variables in condition expressions.

Shorthand syntax
Shorthand syntax	Full syntax in SpEL
`$card_type`	`context['card_type']`
`$(card-type)`	`context['card-type']`
`$card_type:VISA`	`context['card_type'] == 'VISA'`
`$card_type:(MASTER CARD)`	`context['card_type'] == 'MASTER CARD'`

You can include special characters, such as hyphens or periods, in context variable names. However, doing so can lead to problems when the SpEL expression is evaluated. The hyphen might be interpreted as a minus sign, for example. To avoid such problems, reference the variable by using either the full expression syntax or the shorthand syntax $(variable-name) and do not use the following special characters in the name:

Parentheses ()
More than one apostrophe ''
Quotation marks "

When you refer to a context variable in a text response or a dialog node condition, you can use the short syntax.

For example, Hello, $name. If the $name context variable contains Sam, then the response is shown as Hello, Sam.

If you want to reference a context variable by using the full syntax in a text response, be sure to surround the context variable in <? ?>. For example, Hello, <? context['name'] ?>.

If you want to reference a context variable that has multiple fields, such as $context.integrations.chat.browser_info.page_url. To use the full syntax, specify <? context['integrations']['chat']['browser_info']['page_url'] ?>.

Shorthand syntax for entities

The following table shows examples of the shorthand syntax that you can use when you refer to entities.

Shorthand syntax
Shorthand syntax	Full syntax in SpEL
`@year`	`entities['year']?.value`
`@year == 2016`	`entities['year']?.value == 2016`
`@year != 2016`	`entities['year']?.value != 2016`
`@city == 'Boston'`	`entities['city']?.value == 'Boston'`
`@city:Boston`	`entities['city']?.contains('Boston')`
`@city:(New York)`	`entities['city']?.contains('New York')`

In SpEL, the question mark (?) prevents a null pointer exception from being triggered when an entity object is null.

If the entity value that you want to check for contains a ) character, you cannot use the : operator for comparison. For example, if you want to check whether the city entity is Dublin (Ohio), you must use @city == 'Dublin (Ohio)' instead of @city:(Dublin (Ohio)).

Shorthand syntax for intents

The following table shows examples of the shorthand syntax that you can use when you refer to intents.

Built-in global variables

You can use the expression language to extract property information for the following global variables:

Global variables
Global variable	Definition
context	JSON object part of the processed conversation message.
entities[ ]	List of entities that supports default access to the 1st element.
input	JSON object part of the processed conversation message.
intents[ ]	List of intents that supports default access to the first element.
output	JSON object part of the processed conversation message.

Accessing entities

The entities array contains one or more entities that were recognized in user input.

While you test your dialog, you can see details of the entities that are recognized in user input by specifying this expression in a dialog node response:

<? entities ?>

For the user input, today, your assistant recognizes the @sys-date system entity, so the response contains this entity object:

 [
   {
     "entity":"sys-date",
     "location":[0,5],
     "value":"2020-12-30",
     "confidence":1.0,
     "metadata":
     {
       "calendar_type":"GREGORIAN",
       "timezone":"America/New_York"
     },
     "interpretation":
     {
       "timezone":"America/New_York",
       "relative_day":0,
       "granularity":"day",
       "calendar_type":"GREGORIAN"
      }
    }
  ]

If you want to include text in the response, use the toJson() method in the expression to cast the returned entities list into a JSON object. For example:

Recognized entities are: <? entities.toJson() ?>

When placement of entities in the input matters

When you use the shorthand expression @city.contains('Boston') in a condition, the dialog node returns true only if Boston is the first entity that is detected in the user input. Use this syntax only if the placement of entities in the input matters to you and you want to check the first mention only.

Use the full SpEL expression if you want the condition to return true anytime the term is mentioned in the user input, regardless of the order in which the entities are mentioned. The condition entities['city']?.contains('Boston') returns true when at least one 'Boston' city entity is found in all the @city entities, regardless of placement.

For example, a user submits "I want to go from Toronto to Boston." The @city:Toronto and @city:Boston entities are detected and are represented in the array that is returned as follows:

entities.city[0].value = 'Toronto'
entities.city[1].value = 'Boston'

The order of entities in the array that is returned matches the order in which they are mentioned in the user input.

Entity properties

Each entity has a set of properties that are associated with it. You can access information about an entity through its properties.

Entity properties
Property	Definition	Usage tips
confidence	A decimal percentage that represents your assistant's confidence in the recognized entity. The confidence of an entity is either 0 or 1, unless you activate fuzzy matching of entities. When fuzzy matching is enabled, the default confidence level threshold is 0.3. Whether fuzzy matching is enabled, system entities always have a confidence level of 1.0.	You can use this property in a condition to have it return false if the confidence level is not higher than a percent you specify.
location	A zero-based character offsets that indicates where the detected entity values begin and end in the input text.	Use `.literal` to extract the span of text between start and end index values that are stored in the location property.
value	The entity value identified in the input.	This property returns the entity value as defined in the training data, even if the match was made against one of its associated synonyms. You can use `.values` to capture multiple occurrences of an entity that might be present in user input.

Entity property usage examples

In the following examples, the skill contains an airport entity that includes a value of JFK, and the synonym 'Kennedy Airport". The user input is I want to go to Kennedy Airport.

To return a specific response if the 'JFK' entity is recognized in the user input, you might add this expression to the response condition: entities.airport[0].value == 'JFK' or @airport = "JFK"
To return the entity name as it was specified by the user in the dialog response, use the .literal property: So you want to go to <?entities.airport[0].literal?>... or So you want to go to @airport.literal ...

Both formats evaluate to So you want to go to Kennedy Airport... in the response.

Expressions like @airport:(JFK) or @airport.contains('JFK') always refer to the value of the entity (JFK in this example).
To be more restrictive about which terms are identified as airports in the input when fuzzy matching is enabled, you can specify this expression in a node condition, for example: @airport && @airport.confidence > 0.7. The node executes only if your assistant is 70% confident that the input text contains an airport reference.

In this example, the user input is Are there places to exchange currency at JFK, Logan, and O'Hare?

To capture multiple occurrences of an entity type in user input, use syntax like this:
```
"context":{
  "airports":"@airport.values"
}
```
To later refer to the captured list in a dialog response, use this syntax: You asked about these airports: <? $airports.join(', ') ?>. It is displayed like this: You asked about these airports: JFK, Logan, O'Hare.
To capture the literal values for multiple entity mentions, use the following syntax:
```
entities['myEntityName'].![literal]
```

Accessing intents

The intents array contains one or more intents that were recognized in the user input, which is sorted in descending order of confidence.

Each intent has one property only: the confidence property. The confidence property is a decimal percentage that represents your assistant's confidence in the recognized intent.

While you test your dialog, you can see details of the intents that are recognized in user input by specifying this expression in a dialog node response:

<? intents ?>

For the user input, Hello now, your assistant finds an exact match with the #greeting intent. Therefore, it lists the #greeting intent object details first. The response also includes the top 10 other intents that are defined in the skill regardless of their confidence score. (In this example, its confidence in the other intents is set to 0 because the first intent is an exact match.) The top 10 intents are returned because the "Try it out" pane sends the alternate_intents:true parameter with its request. If you are using the API directly and want to see the top 10 results, be sure to specify this parameter in your call. If alternate_intents is false, which is the default value, only intents with a confidence higher than 0.2 are returned in the array.

[{"intent":"greeting","confidence":1},
{"intent":"yes","confidence":0},
{"intent":"pizza-order","confidence":0}]

If you want to include text in the response, use the toJson() method in the expression to cast the returned intents list into a JSON object. For example:

Recognized intents are: <? intents.toJson() ?>

The following examples show how to check for an intent value:

intents[0] == 'Help'
intent == 'Help'

intent == 'help' differs from intents[0] == 'help' because intent == 'help' does not throw an exception if no intent is detected. It is evaluated as true only if the intent confidence exceeds a threshold. If you want to, you can specify a custom confidence level for a condition, for example, intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Accessing input

The input JSON object contains one property only: the text property. The text property represents the text of the user input.

Input property usage examples

The following example shows how to access input:

To execute a node if the user input is "Yes", add this expression to the node condition: input.text == 'Yes'

You can use any of the String methods to evaluate or manipulate text from the user input. For example:

To check whether the user input contains "Yes", use: input.text.contains( 'Yes' ).
Returns true if the user input is a number: input.text.matches( '[0-9]+' ).
To check whether the input string contains ten characters, use: input.text.length() == 10.