Language
These are the components that are available in the Language category of YAML-based dialog flow editor.
System.Intent
This component is not available for skills developed with the Visual Flow Designer. Instead, intents are resolved automatically when there is no active flow. See Intent Detection and Resolution.
Property | Description | Required? |
---|---|---|
variable |
Holds the value that the language processing
framework resolves from the user input. For example, our sample
skill bots define this property as variable=iResult
(with iResult: "nlpResult" defined as one of the
context variables). You don’t need to name the
variable iResult . This name is a convention used in
our sample code and sample skills. Whatever variable name you use
for nlpResult , be sure to use it consistently
across the dialog flow.
|
Yes |
optionsPrompt |
The title for the list of intents when you set a
value for the Win Margin option. By default,
this string value is Do you want to .
The default value for this property is stored in the skill's resource bundle. To change it, click , select the Configuration tab, and update the Intent - optionsPrompt key. If you use the skill's resource bundle to change the default message, then you don't need to include the property in the component unless you want to override the default. |
No |
botName |
The name (not the display name) of the skill that resolves the intent. Use this property if you decide to resolve the user input using the model of a separate skill rather than the current skill. Using this approach might be beneficial if you want resolve the intent based on a model with a more narrowly defined domain than the domain required by your primary use case. | No |
botVersion |
Specifies the version of the skill. The default value
is 1.0 (if you don't specify the version number).
|
No |
sourceVariable |
The language processing framework resolves the
intent using the sourceVariable as the input.
Important: You can't use this
property in combination with the |
No |
daIntercept |
For calls to System.Intent ,
determines whether the digital assistant can intercept and reroute
the user input to other skills. These are the possible values:
|
No |
translate |
Overrides the value set for the
autoTranslate context variable here. If
autoTranslate is not set, or set to
false , you can set this property to
true to enable auto-translation for this
component only. If the autotranslate context
variable is set to true , you can set this property
to false to exclude this component from
auto-translation.
Important: You
can't use this property in combination with the
|
No |
Q&A Properties for the System.Intent Component
Property | Description | Data Type | Default Value |
---|---|---|---|
qnaEnable |
Enables the routing to the Q&A module. If you set this to true (routing enabled) you also need to define the Q&A transition action (none or exit ). See Q&A Transitions.
|
boolean | false |
qnaBotName |
The name (not the display name) of the skill with the Q&A module. If you
don’t define this property, then the value defined for
System.QnA component’s botName
property is used instead.
|
string | N/A |
qnaBotVersion |
The version of the skill with the Q&A module. By default, it's 1.0. This value is optional | int | N/A |
qnaTimeout |
The time, in milliseconds, that the skill waits for the Q&A server to respond to the user input. | long | 5000 |
qnaUseResult |
Setting this option to true (the default), enables the skill to
query the Q&A server with the user input. The skill then uses
the results of this query (the matches) to set the routing. When you
set this property to true , the skill will display
the View Answers link only when there are matches. Setting it
to false , displays the View Answers link at all
times.
|
boolean | true |
qnaSkipIfIntentFound |
When set to true , the skill bypasses Q&A when an there’s an
intent match. The default value (false ), enables
the skill to query the QnA server with user utterance and also
present QnA as an option.
|
boolean | false |
optionsPrompt |
Q&A is displayed if it’s enabled for the Tip: For foreign (non-English) languages, reference a resource bundle. See Reference Resource Bundles in the Dialog Flow |
string | Do you want to |
optionsQnaLabel |
A label for action in the options ( Tip: For foreign (non-English) languages, reference a resource bundle. See Reference Resource Bundles in the Dialog Flow |
string | Questions |
qnaMatchFields |
Sets the Q&A fields used to match the user message. Valid
values include:
|
string | all |
qnaMinimumMatch |
Sets the minimum and maximum percentage of tokens that any Q&A pair must contain in order to be considered a match. To return the best matches, we tokenize the utterances that the Intent Engine resolves as questions. These tokens are formed from word stems and from various word combinations. As a result, a large set of tokens can be generated from an utterance. Because of this, it’s unlikely that any Q&A pair could contain all of the key words and variants. Therefore, we don’t recommend that you change this setting from its default, Having 50% of the generated tokens (the default maximum level) means that the Q&A pair can be considered a relevant match if it has all of the key words from the utterance. If this maximum level can’t be met, then a minimum level of 25% would suffice. If you change these settings—particularly by increasing the maximum to more than 50%—then the Q&A pair would not only need to contain all of the key words, but must also match additional tokens. That said, if you want to reduce the chance of missing a relevant match—and can tolerate returning irrelevant matches in the process—then you can add an even lower threshold. For example: If you want to minimize irrelevant matches, then you can increase the levels (say, Important: If you don’t want to use the default levels, then you need to set the |
string | 50%,25% |
qnaUseSourceVariable |
When set to true , the Q&A matching is based on the value stored in the System.Qna’s sourceVariable property, not the user input.
|
boolean | false |
System.MatchEntity
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Match Entity.
The System.MatchEntity
calls the Intent Engine to extract entity information
from the text held by the sourceVariable
property. If a match exists for the
variable's entity type, the variable is set with this entity value.
Property | Description | Required? |
---|---|---|
sourceVariable |
The variable that holds the input value. | Yes |
variable |
The name of the context variable. The value of this variable can be used in a subsequent System.SetVariable component to extract a specific entity using a FreeMarker expression. For example, to extract an EMAIL entity value: ${userInputEntities.value.entityMatches['EMAIL'][0]} |
Yes |
This component also has two predefined transitions: match
and
nomatch
.
Transition | Description |
---|---|
match |
Directs the Dialog Engine to go a state when the entities match. |
nomatch |
Defines the Dialog Engine to go to a state when the entities don’t match. |
System.MatchEntity
component matches the user-provided value stored in the mailInput
variable against the EMAIL entity type that’s been defined for the mailEntity
variable. If the user input satisfies the entity type by being an e-mail address, then the System.MatchEntity
component writes this value to the mailEntity
variable that’s echoed back to the bot user ("You entered ${mailEntity.value.email}"
). When the values don’t match, the Dialog Engine moves to the nomatch
state.
The
System.MatchEntity
component resolves a single value.
context:
variables:
iResult: "nlpresult"
mailInput: "string"
mailEntity: "EMAIL"
states:
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
displayMailAdresses: "askMail"
unresolvedIntent: "dunno"
askMail:
component: "System.Text"
properties:
prompt: "Please provide a valid email address"
variable: "mailInput"
transitions:
next: "matchEntity"
matchEntity:
component: "System.MatchEntity"
properties:
sourceVariable: "mailInput"
variable: "mailEntity"
transitions:
actions:
match: "print"
nomatch: "nomatch"
print:
component: "System.Output"
properties:
text: "You entered ${mailEntity.value.email}"
transitions:
return: "done"
nomatch:
component: "System.Output"
properties:
text: "All I wanted was a valid email address."
transitions:
return: "done"
dunno:
component: "System.Output"
properties:
text: "I don't know what you want"
transitions:
return: "done"
System.DetectLanguage
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Detect Language.
source
property:
context:
variables:
autoTranslate: "boolean"
translated: "string"
someTranslatedText: "string"
states:
setAutoTranslate:
component: "System.SetVariable"
properties:
variable: "autoTranslate"
value: true
transitions:
next: "detect"
detect:
component: "System.DetectLanguage"
properties:
source: "someTranslatedText"
useExistingProfileLanguageTag: true
transitions:
...
The
System.DetectLanguage
component sets a variable named
profile.languageTag
with the locale string. You can set variables with the
current language when you use this variable in a value expression
(${profile.languageTag}
).
The
profile.languageTag
takes precedence over the profile.locale
variable that’s set by the messenger
client.
The useExistingProfileLanguageTag
property is used when a skill
is part of a digital assistant that has a translation service. This enables the skill to use
the language that is detected by the digital assistant immediately. Otherwise, the skill might
provide a message or prompt in English before the language is (re-)detected. If the skill is
not in a translation-enabled digital assistant, the property is ignored.
The profile.locale and profile.languageTag Variables
The use of a particular resource bundle and the translations for both the UI labels the component messages themselves all depend on the user’s language that’s stored in the profile.locale
and profile.languageTag
variables.
The ways these variables get set depend on the language mode of the skill:
- For skills that use native language support, the language is detected automatically and the these variables are populated with the appropriate value, unless the variables have already been assigned values.
- For skills that use a translation service:
- The value for the
profile.locale
variable is derived from the user’s messenger client.Note
profile.locale
supports values in ISO language-country or ISO language_country formats. - The value for the
profile.languageTag
variable is provided by the System.DetectLanguage component.
- The value for the
The value set for the
profile.locale
variable can determine the locale-specific formats for the DATE, CURRENCY, and NUMBER entities even
when a value has been set for the profile.languageTag
variable.
-
setLocaleToGerman: component: "System.SetVariable" properties: variable: "profile.locale" value: "de"
-
setLanguageTagToGerman: component: "System.SetVariable" properties: variable: "profile.languageTag" value: "de"
-
setLanguageToVariableValue: component: "System.SetVariable" properties: variable: "profile.languageTag" value: "${language_preference_var.value}"
-
setLocaleToLanguageTag: component: "System.SetVariable" properties: variable: "profile.locale" value: "${profile.languageTag}"
-
setTagToLocale: component: "System.SetVariable" properties: variable: "profile.languageTag" value: "${profile.locale}"
Tip:
You can implement a choice list of languages by comparing the locale value stored in these variables, or in a custom user database table, against a list of supported languages. If the detected language isn’t on this list, you can prompt the user to choose one and then set theprofile.languageTag
with this value.
System.TranslateInput
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Translate Input.
This component sends specified text to the skill's translation service and then stores the English translation. It relies on the skill being configured with a translation service, which recognizes the language from the user's input and translates it into in English. This component doesn't work with skills that use the Natively Supported language mode.
Use this component when you need to process the raw input text before having it translated. For example, you might want to remove some personal data from the user input before sending it to the translation service.
Property | Description | Required? |
---|---|---|
source |
Specifies the text values to be translated into English. | No |
variable |
The variable that holds the English translation of the text. | Yes |
Because the System.TranslateInput
component leverages the translation service, which already detects the user’s language, this component doesn’t need to follow states that detect or set the language as described in Add a Translation Service to Your Skill. As a result, you can store the English translation from direct user input, or from a source
variable.
Direct Input Translation
System.TranslateInput
component stores the English translation
of direct user input in its variable
property. The following code snippet
shows how user input like “Hallo, ich bin ein Mensch” in the translatedString
variable is stored as “Hello, I am a
human”.context:
variables:
translatedString: “string”
sourceString: “string”
...
states:
...
translateInput:
component: "System.TranslateInput"
properties:
variable: "translatedString"
The source Variable
sourceString
variable holds the user
input. (This input, for example, may have been gathered by a Common Response component.) After
the System.TranslateInput
completes its processing, the English translation
is stored in the translatedString
variable.context:
variables:
autoTranslate: "boolean"
translatedString: "string"
sourceString: "string"
...
states:
...
translateInputString:
component: "System.TranslateInput"
properties:
source: "sourceString"
variable: "translatedString"
transitions:
...
The
System.TranslateInput
component can’t translate data objects or arrays that are stored in a context variable by a
custom component. This content can only be translated when the variable is referenced by a
component that uses autotranslation. For example, the System.TranslateInput
component can’t translate a data object like {”product”: “scissors”, “color”:
“silver”}
as scissors and silver.
The sourceVariable Property
System.Intent
’s sourceVariable
property holds the value processed by the component, you can use it with the
System.TranslateInput
component to insert translated text. The following
snippet shows assigning the translated
variable value so that it can be
processed by the NLP engine.
translate:
component: "System.TranslateInput"
properties:
variable: "translated"
transitions:
next: "intent"
intent:
component: "System.Intent"
properties:
variable: "iResult"
sourceVariable: "translated"
...
System.TranslateOutput
This topic covers use of this component in YAML mode. For information on using it in the Visual Flow Designer, see Translate Output.
System.TranslateOutput
component allows you to translate text to
the user’s language. The component takes the value defined for the source
property. It translates the text into the language detected by the
System.DetectLanguage
component or by the profile.locale
variable and then stores it in the variable
property.
Properties | Description | Required? |
---|---|---|
source |
The text to be translated, or a FreeMarker expression that references a variable whose value needs to be translated. | Yes |
variable |
Holds the translated text. | Yes |
System.Output
component, which would otherwise
display autotranslated text, still outputs translated text, but here it outputs the
translation of the text defined for the source
property. unresolvedTranslate:
component: "System.TranslateOutput"
properties:
source: "Sorry I don't understand"
variable: "someTranslatedText"
transitions:
next: "unresolved"
unresolved:
component: "System.Output"
properties:
text: "${someTranslatedText}"
transitions:
return: "unresolved"
System.Qna
System.Qna
component.
Name | Description | Required? | Default Value | |
---|---|---|---|---|
botName |
The name (not the display name) of the skill with the Q&A module. | No | N/A | |
botVersion |
The version of the
skill that's identified by the botName property. You can define the
botName property without also defining the
botVersion property. However, you can't define
botVersion without also defining botName :
botVersion is ignored when you don't also define the
botName property. As a consequence, its default version
(1.0 ), only applies if you also define the
botName property. To route to another version of the skill, you
need to define the botName property and set the
botVersion property with the target version.
|
No | 1.0 | |
highlighter |
The method used to highlight the most relevant text in each answer. The valid values are:
|
No | system |
|
highlightLength |
The number of characters to be highlighted in each answer. | No | 100 | |
sourceVariable |
The language processing framework
resolves the Q&A matching using the value stored by the
sourceVariable , not the user input. You activate this matching by
setting qnaUseSourceVariable: true for the System.Intent component. For
example:
|
No | N/A | |
transitionOnTextReceived |
Transitions from the state defined with the
System.QnA component when the user enters free text.
|
No | true |
|
keepTurn |
The |
No | false (when configured as a boolean)
|
|
matchListLimit |
Limits the pagination for the answers | No | 5 | |
categoryListLimit |
Limits the pagination of the categories | No | 5 | |
resultLayout |
The layout for the matching
answers. Valid values: horizontal and
vertical .
|
No | horizontal | |
minimumMatch |
Sets the minimum and maximum percentage of tokens that any Q&A pair must contain in order to be considered a match. To return the best matches, we tokenize the utterances that the
Intent Engine resolves as questions. These tokens are formed from word stems and
from various word combinations. Depending on the length of the user message, the
process can generate a large set of tokens. Because it's unlikely that any Q&A
pair can match all of them, we recommend that you set the matching level at
In this setting, the Q&A pair can be considered a relevant if it matches 50% of the tokens. If this maximum level can’t be met, then a minimum level of 25% will suffice. If you want to reduce the chance of missing a relevant match—and can
tolerate returning irrelevant matches in the process—then you can add an even
lower threshold as a fallback. For example: If you want to minimize irrelevant matches, then you can increase
the percentage (say, Important: If you don’t want to use the default levels when
testing, then you need to set the |
No | 50%,25% | |
matchfields |
Sets the Q&A fields used to
match the user message. Valid values include:
|
No | all |
|
enableCategoryDrilldown |
Set to true to
display a drill down by category.
|
No | true |
|
exitLabel |
The label text for exiting the Q&A module. | No | Exit Questions |
|
viewAnswerLabel |
The label text for the view action for an answer detail. | No | View |
|
moreAnswersLabel |
The label text for view action for more answers. | No | More Answers |
|
answersLabel |
The label text for the view actions for answers in a specific category. | No | Answers |
|
categoriesLabel |
The label text for the categories that match the utterance. | No | Categories |
|
subCategoriesLabel |
The label text for the view action for the subcategories. | No | Sub-Categories |
|
moreCategoriesLabel |
The label text for the view action for more categories. | No | More Categories |
Increase the Precision of the Returned Q&A Using minimumMatch
While the default setting of 50%,25%
returns accurate
Q&A pairs, you may want your skill to return fewer, more precise results by
increasing the percentage. For example, you may want your skill to only return a Q&A
pair when it matches a high percentage of the tokens, or instead route the user to a
live agent.
In such a scenario, increasing the percentage for the minimumMatch
property to 80% can return more accurate Q&A matches, particularly for longer
messages. The same may not be true for shorter messages, which are typically comprised
of three to seven words, with about 50% of them being ignored words (stop words). For
example, the user question What is account security? , for example, the system
detects two tokens, account and security. When minimumMatch
is set to
80%, only one of these tokens gets returned (80% of 2 is 1.6, which gets rounded down to
1), when ideally, both of them should. In this case, the skill might return Q&A
pairs that generally describe accounts, which is too broad a response. The skill should
have returned only the Q&A about account security, or returned nothing at all.
minimumMatch
property to return accurate Q&A for
short messages, enter the number of tokens that must be matched, a less-than operator
(<) and the required matching level when the message contains a higher number of
tokens. For
example: qna:
component: "System.QnA"
properties:
minimumMatch: "3<80%"
transitions:
actions:
none: "unresolved"
next: "intent"
In
this snippet, if message contains 1 to 3 tokens, then the Q&A pair must match all of
them for the skill to return it to the user. In terms of the scenario, this setting
would only return a Q&A pair that matched account security. When the message has
four or more tokens, then the Q&A pair only needs to match 80% of them. qna:
component: "System.QnA"
properties:
minimumMatch: "3<80% 8<70% 12<65%"
transitions:
actions:
none: "unresolved"
next: "intent"
Per
the minimumMatch
setting in this snippet, the skill returns Q&A
only when the following tokens are matched.
Number of Tokens in the Message | The Number of Tokens that Must Match |
---|---|
1 | 1 |
2 | 2 |
3 | 3 |
4 (80% match) | 3 (3.2, rounded down to 3) |
5 (80% match) | 4 |
6 (80% match) | 4 (4.8, rounded down to 4 |
7 (80% match) | 5 (5.6, rounded down to 5) |
8 (80% match) | 6 (6.4 rounded down to 6) |
9 (70% match) | 6 (6.3, rounded down to 5) |
10 (70% match) | 7 |
11 (70% match) | 7 (7.7, rounded down to 7) |
12 (70% match) | 8 (8.4, rounded down to 8) |
13 (65% match) | 8 (8.45, rounded down to 8) |
keepTurn key-value Maps and Transition Actions
keepTurn
property as a map whose keys describe
the transitions.
Key | Description | Default Value |
---|---|---|
next |
When set to false , the skill relinquishes
control when the dialog transitions to the next state. The skill
won’t process any user input until the Dialog Engine move to the
next state.
|
false |
none |
When set to true , the skill retains control when
a none transition action is triggered because
there’s no question that can be returned for the user input.
|
true |
exit |
When set to true , the skill retains control when
an exit transition action has been
triggered.
|
true |
textReceived |
When set to true , the skill retains control of
the conversation when transitionOnTextReceived is
set to true which signals the Dialog Engine to
transition from the state.
|
true |