Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Introduction to Dialog

What is a Dialog?

As users interact with Bixby, it communicates back to them in various ways. This could be as simple as the result of a user utterance, or it could be a request for additional information. These messages, or dialog, tell users what is happening, what has happened, and what can happen next.

A typical interaction might start with a user asking "What's the weather like in Palo Alto, California this Friday?" After Bixby processes this request, the user sees this sequence of messages:

Checking the weather...

Here's the weather on Friday for Palo Alto, CA

Bixby dynamically generates messages to communicate with the user. These messages complement layouts by giving status information, paraphrasing results, asking questions, and much more. Bixby provides some default messages for results, but you might want to add your own custom messages to truly match the tone and approach of your capsule. You can improve these messages by writing custom dialog files.

Caution

You should wait until your models are fully formed before working on dialog.

In its simplest form, a dialog file looks like this:

dialog (%mode%) {
match: %match-pattern%
template (%text%)
}

The template defines the actual content of the dialog message. The dialog mode, match pattern, and control flows all serve one purpose: to determine the single template that should be served to the user based on the current context. Ultimately, Bixby evaluates the template to produce a string. However, you can also use Expression Language to create dynamic content. In particular, you can compose the message using formatting functions and invoke other dialog. If you do not want to show any message, or you would like to remove a default Bixby message, you can use an empty template template().

Each dialog specifies a match pattern, which can link to a concept or an action or something more complex. Bixby evaluates the match pattern to decide the dialog to use based on the evaluation context. Should multiple match patterns qualify, Bixby selects the most specific one.

You should start by defining dialog for simple match patterns and use them as building blocks for more complex ones. You can use the match pattern to bind values for use in the dialog template. Dialogs support simple conditional logic and template substitution. You can even use a switch with Expression Language functions such as plural, state, and size.

Dialog shows up in different situations based on the mode, which can fall into two major categories: events and fragments.

Events describe how to notify the user about something that has happened or needs to happen. For example, one of the most common events is a result. Here's an example dialog for the results of a tip calculator:

dialog (Result) {
match: viv.gratuity.CalculateTip (_)
if (exists(billSplit) && billSplit > 1) {
if (exists(exclusions) && exclusions.value > 0.0) {
template ("Your #{value (tipPercent)} tip on #{value (subtotal)} total for #{value(billSplit)} people excluding #{value(exclusions)} is #{value (tip)} each")
} else {
template ("Your #{value (tipPercent)} tip on #{value (subtotal)} total for #{value(billSplit)} people is #{value (tip)} each")
}
} else {
if (exists(exclusions) && exclusions.value > 0.0) {
template ("Your #{value (tipPercent)} tip on #{value (subtotal)} total excluding #{value(exclusions)} is #{value (tip)}")
} else {
template ("Your #{value (tipPercent)} tip on #{value (subtotal)} total is #{value (tip)}")
}
}
}

The resulting user interface looks likes this:

tip calculator view

In this case, the example dialog above helps to determine what the user sees after a tip is calculated. Notice there are if/else statements that account for tip splitting and tax.

As compared to events, fragments form the building blocks of an event. They determine how to format concepts and actions within an event message.

There can be multiple dialog fragments that make up a specific dialog event.

When customizing a dialog event, keep variable dialog in dialog fragments. You should define dialog incrementally, starting with the simplest modes, and use them as building blocks for the more complex ones: Concept, Value, Input, Action, Progress, NoResult, Result.

Execution State and Concept Features

You can use execution states to adjust a verb phrase based on the status of an action.

The available execution states for dialog are:

  • Pre: dialog before an action occurs
  • Mid: dialog while an action is occurring
  • Post: dialog after an action occurs

For example, if a user is buying event tickets, here is an example action dialog that has execution states covering stages of the transaction:

dialog (Action) {
match {
ticketmaster.Pay (action)
}
switch (state(action)) {
case (Pre) {
template ("buy tickets")
}
case (Mid) {
template ("completing your purchase")
}
case (Post) {
template ("processed payment")
}
}
}

The execution state will be fully settled before any dialogs are requested and resolved.

Concept features determine whether a concept refers to one, many, or is location-specific.

The available features for dialog are:

  • Definite: a concept referring to single cardinality
  • Indefinite: a concept referring to a multiple cardinality (group)
  • Proximal: a concept referring to a location

For an example of Definite and Indefinite, here is a concept fragment representing either Definite or Indefinite cardinality for movie properties such as genre or release date:

dialog (Concept) {
match: _ (this) {
from-property: movie.Movie (source)
}
template ("#{concept (this)} of #{size(source) == 1 ? concept (source, 'Definite') : concept (source, 'Indefinite')}")
}

When size is one, the output would read director of the movie. Otherwise, Bixby says directors of a movie.

In this dialog event, which uses Proximal, the user is asked to select a specific point of interest:

dialog (Selection) {
match {
geo.PointOfInterest (this) {
from-output: geo.FindPointOfInterest (action)
}
}
choose (First) {
if (exists(action.name)) {
template("Which #{value (action.name)}?")
} else {
template("Which one of #{concept (this, 'Proximal')}?")
}
}
}

If the first template is chosen, Bixby might say something like Which Bay Bridge?. Otherwise, it would say Which one of these Bay Bridges?

Dialog Events

Bixby generates events before, during, and after execution, and displays some of these events to the user through dialogs. We call these dialog events. When presenting an event, Bixby tries to form complete sentences that fully describe the surrounding context.

To create a new dialog event template, start by identifying the event mode you need. Run your utterance in the Simulator, and you can see the dialog events that each dialog triggers. In the Inspector of the Debug Console, you can expand the Dialog section. Click the dialog you want to inspect, and it will tell you which mode is being used to trigger that dialog.

Some of the most common dialog events are:

  • Result: inform the user about results in a succinct way.

      dialog (Result) {
    match {
    viv.request.Food
    }
    template (Here are some food options)
    }
  • NoResult: inform the user that no result is available.

      dialog (NoResult) {
    match: viv.air.AirplaneHasWifi
    template ("I couldn't find any information on wifi availability.")
    }
  • Progress: inform the user about an ongoing action.

      dialog (Progress) {
    match {
    viv.hotel.AvailableHotel
    }

    template ("Checking hotel availability...")
    }
  • Selection: prompt the user to make a choice from results.

       dialog (Selection) {
    match {
    viv.florist.Occasion
    }
    template("What's the occasion?")
    }

You can read more about dialog events and see a list of them in reference documentation.

Dialog Fragments

Whenever Bixby generates dialog, it refers to concepts and actions and render dialogs using dialog fragments.

The dialog fragment modes are:

  • Action: A verb phrase describing action state.
  • Concept: A descriptive noun phrase for one or more concept values.
  • Input: An action input required for one or more concept value.
  • Value: The canonical representation of one or more concept values.
  • Structure: A Value fragment for structures.

To provide a minimal level of dialog for capsules, Bixby includes a number of default dialog fragment templates that cover common cases.

You can read more about and see a list of dialog fragments in reference documentation.

Note

Dialog fragments are independent of Dialog Events. Fragments are never invoked on their own, but are used as building blocks inside dialogs that are triggered by events.

If you have fragments that are optional, you can put them in square brackets ([]). If a section of a template within these brackets fails to render, that section will be skipped.

template ("Here are some[ #{value(input.decade)}][ #{value(input.genre}] movies[ with #{value (input.actor)]")

Overwriting Default Dialog

Keep in mind that, by default, Bixby provides default dialog for your capsule. However, you will likely find cases where it seems awkward or even ungrammatical. For example, suppose we send this input structure to a flight search action:

// Find the best seats on a United Airbus 319 plane
viv.air.AirplaneSeatDetails {
viv.air.CarrierName (United Airlines, Inc.)
viv.air.AirplaneModelName ("Airbus 319 (319)")
viv.rating.Score (5)
}

Here is the Progress event dialog:

Getting airplane seat details where the airplane model name is Airbus 319 (319), where the carrier name is United Airlines, Inc., and where the score is 5.0...

This is the Result event dialog:

Here are 10 airplane seat details where the airplane model name is Airbus 319 (319), where the carrier name is United Airlines, Inc., and where the score is 5.0:

Notice that, in the phrase "airplane seat details," the plural form is wrong.

To correct this, you can define a custom dialog:

  1. Open the File menu and select New File.
  2. Choose Dialog in the Type drop-down menu.
  3. Provide a name for the file.
  4. Select Create.
  5. Enter code similar to the following:

     dialog (Concept) {
    match: this(viv.air.AirplaneSeatDetails)

    switch (plural(this)) {
    case (One) {
    template (airplane seat description)
    }
    default {
    template (airplane seat descriptions)
    }
    }
    }

Now the above query produces a better dialog:

Getting airplane seat descriptions where the airplane model name is...

Further Refinement of Dialog

Dialogs are built recursively by invoking the dialogs for Events and Fragments inside. To understand the inner composition of these dialogs, you can always take a look in the Debug Console. Specifically, you can take a look at the X-Ray Pane to discover which concepts and their values are being called and from which file.

If you are combining different parts of the dialog into a single output, you might want to change the order of those parts. In order to do this, you will need to find the parent of the parts and change the order there.

For example, let's say Bixby has a NoResult event that says "I can't find any business" and an Input fragment that says "where the city is Beijing". Combined, Bixby might say "I can't find any business where the city is Beijing". To switch the order of this, you would find the parent of both the event and the input fragment (in this case, No Result for Business) and change the order there, like in the following example:

dialog(NoResult) {
match: yourNamespace.YourBusiness(output) {
from-output: yourNamespace.YourFindBusiness(action)
}
template("[#{joinAs('input', action.city, action.keyword)} ] I can't find any #{concept(output.without(action))}")
}

This would produce "I can't find any in Beijing and I can't find any business".

There might be situations where you don't want dialog to appear. In this case, you can use an empty dialog template (template( )).

Dialog Template Localization

Some languages have different inflected forms of their words based on the gender and plurality of the term to which they are linked. Since these terms may be filled in at runtime through templates (e.g., #{concept(this)}), Bixby supports a special syntax for handling agreement of gender and case within dialog templates.

Nouns should be bracketed with %{id:noun}, where id can be any number:

%{1:chose}

These are used to match against agreement expressions of the form @{id<type>:val1,val2}:

@{1g:le,la}
  • id is the number of the term that this expression should be matched against;
  • <type> is a locale-specific letter code indicating the kind of agreement being evaluated, in this case g for gender (c for case would also be common);
  • val, val2, etc., are the values for each gender or case, in a locale-specific order. These values can be the empty string.

Take the following example template:

template("Et voilà @{1g:le,la} %{1:#{concept(this)}} trouvé@{1g:,e}")

Template expressions are evaluated first; if concept(this) evaluated to chose ("thing" in French), the template string would now be:

Et voilà @{1g:le,la} %{1:chose} trouvé@{1g:,e}}

Now, the agreement expressions would be processed. The gender of chose (female) would be determined by Bixby and the correct values would be substituted in:

Et voilà la chose trouvée

The letter codes for agreement type and the orders are locale-specific. In addition, some locales may execute a final post-processing step that adjusts spelling based on context (e.g., changing "ce ingrédient" to "cet ingrédient").

Currently, the only language Bixby has agreement processing rules for in templates is French:

  • The type must be g for gender agreement
  • Gender-specific values are ordered masculine, feminine: @{1g:le,la}