Bixby Developer Center

Dialog Affirmation

This capsule demonstrates how to effectively use a combination of template macro keys to create a variety of dialog responses to affirm an action from a user. Adding multiple dialog affirmations makes Bixby more user-friendly and natural sounding.

Download Capsule

Note

Because you cannot submit a capsule with the example namespace, in order to test a sample capsule on a device, you must change the id in the capsule.bxb file from example to your organization's namespace before making a private submission.

For example, if your namespace is acme, change example.dialogAffirmation to acme.dialogAffirmation.

Testing This Capsule

You can test this sample capsule with the following utterance:

"Turn on smile"

The Simulator returns a smile using a simple result view that consists of a single-line of text, as well as one of several dialog options, like the following:

"Sure thing, smile is on!"

How the Template Macros Work

This sample capsule demonstrates a much more layered approach of using template macro definitions. Within the resources/en-US/template-macro-defs.macro.bxb file, you can see four separate macro-def keys defined. Some of these keys rely on Expression Language formatting functions or other macro-def keys defined within this file.

Here is how the template macros parses:

  1. The SMILE_RESULT template macro is called directly in the result view by the message key:
  message {
macro (SMILE_RESULT)
}

View 2aae7d7 on GitHub

  1. The SMILE_RESULT uses the macro() EL formatting function, calling on the AFFIRM template macro with the SMILE_ON template macro as the AFFIRM macro's parameter:
macro-def (SMILE_RESULT) {
content: template ("#{macro('AFFIRM', macro('SMILE_ON'))}")
}

View f61843b on GitHub

// Core text response to turning on the smile, in lower case
macro-def (SMILE_ON) {
content: template ("smile is on")
}

View f61843b on GitHub

  1. The AFFIRM template macro returns either a combination of an affirmation and smile is on or simply Smile is on. It uses the choose(Random) control flow function to randomize which dialog is returned. Both options have a 50% chance of being returned.
// Pick a random affirmation (or none) and prepend it to the core text content with the appropriate capitalization and punctuation
macro-def (AFFIRM) {
params {
param (lowerCaseText) {
type (viv.core.Text)
}
}
content {
choose (Random) {
template ("#{title(lowerCaseText)}!") // 50% capitalized sentence without affirmation
template ("#{macro('AFFIRMATION')}, #{lowerCaseText}!") // 50% capitalized affirmation followed by a comma and the lower case text.
}
}
}

// Pick a random affirmation from a bag of words
macro-def (AFFIRMATION) {
content {
choose (Random) {
template (Okay)
template (Alright)
}
}
}

View f61843b on GitHub

  • If it chooses just the SMILE_ON text, it uses the title() EL formatting function to capitalize the first letter.
  • If it chooses to use an affirmation, the AFFIRMATION template macro is called, then a comma is printed, then the passed lowerCaseText parameter text, which is the smile is on.
  1. The AFFIRMATION template macro again uses the choose(Random)control flow key to randomly choose one of the options listed. Several of the options are repeated to increase the chance of that response being chosen. For example, there are six copies of template (Okay), giving it a 30% chance of being picked out of the twenty affirmation template choices.

Notice that the AFFIRMATION template macro doesn't need to use an additional template macro to format the final dialog because all the templates are already formatted with the first letter capitalized and the original text is lower-case. For example, "Okay, smile is on".

Note

Make sure that when you write your own dialog affirmations, you follow the Dialog Best Practices and the Writing Dialog Design Guidelines.