Bixby's planner takes user-supplied input values and your capsule's models to construct a program that reaches a specific goal, such as displaying tomorrow's weather conditions, or presenting a list of local Italian restaurants. However, a user utterance might not include all the information that Bixby needs to reach its goal. In this case, Bixby might interrupt execution to ask the user for more information. Bixby then has an intermediary step with a recovery goal: it uses the user's response from the prompt to create the type of information needed to continue execution and reach the final goal.
If the user asks "how much are flights to New York City next Friday," the utterance includes neither an arrival nor a departure airport. Bixby can use location services to find the closest major airport to the user and assume that it is the departure airport. It could also use previous preference learning to know that, for example, the user lives in Fremont, California, and prefers to fly out of Oakland rather than San Jose. But there are two airports in New York City, La Guardia and John F. Kennedy. Unless it knows a previously-expressed preference from the user, Bixby will need to prompt the user to choose which airport.
Bixby prompts users when a cardinality violation has occurred: a required input has no value available to it, or an input that can take only a single value has multiple values available to it (such as the airport example above). In general, Bixby tries to prompt users as infrequently as possible. An input could have a default-init
that yields a value, it could have selection rules or selection learning that yield a value, or it could have learned a user's preference for a value. The user is prompted for a value when Bixby cannot resolve a cardinality violation on its own.
There are three common types of prompts Bixby might give a user:
A value prompt occurs when a required input is missing a value, and Bixby needs that value to continue execution. In the dice capsule from the Quick Start Guide, if the user asks "Roll dice" and the RollDice
action doesn't provide a default for NumDice
, Bixby will prompt for the number of dice to roll.
A selection prompt occurs when a max cardinality One
input has multiple possible values and the user must select the correct one. This can happen, for example, if the user searches for hotels by city name, and the search action returns multiple possible cities with that name.
A confirmation prompt occurs before Bixby executes a particular action. Generally, it's used before executing actions that have side effects, such as completing a purchase or sending a message.
Confirmation prompts are explicitly generated by your capsule by the confirm
key. Value prompts and selection prompts are generated by Bixby when cardinality violations for inputs occur and cannot be resolved without user input:
min (Required)
input has no values available, the user will be prompted for that value.max (One)
input has multiple values available, the user will be prompted to select a single value from the available values.In addition, the min-preferred
and max-preferred
keys can be used to affect when Bixby prompts for inputs:
min (Optional)
cardinality and min-preference (Required)
indicates that an input does not require a value, but having a value is preferred. This will cause Bixby to prompt the user the first time the input is used in an action and has no value. If no value is provided, the action continues without it.max (Many)
and max-preferred (One)
indicates that an input allows multiple values, but prefers just one. If only one value is available to the input, the user will not be prompted. If there are two or more values, Bixby will prompt the user to select one or more items from the available values.When a user is at a prompt, utterances will be locked to the type being prompted for, and the user must answer the prompt to continue. You can add training examples specifically for prompts.
When at a prompt, the user is locked into a conversation with the current capsule for a period of time before it times out. This is known as capsule lock, and it ensures that subsequent utterances are always sent to the current capsule for a short amount of time. In hands-on mode, the capsule lock timeout is 15 seconds. In hands-free mode, the user will be re-prompted after 7 seconds. If the user doesn't respond within those 7 seconds, capsule lock ends.
Currently, only mobile devices support capsule lock.
Users know they are locked into a capsule on mobile when they see the message "You're now talking to %capsule-name%" in the action zone of the screen. For example, users are locked into a conversation with the Meme Generator capsule below:
Capsule lock is triggered under the following conditions:
followup
in the result viewCapsule lock ends when users do any of the following:
X
During capsule lock, it is possible for Bixby to detect a user's response as being "off-topic," which will cause the utterance to be re-interpreted in a non-modal way. Bixby then tries to address the off-topic utterance in the context of the current capsule.
The flag-as-off-topic
effect can also be used to force Bixby to re-interpret the utterance. For instance, if a weather capsule prompts the user to select between multiple options ("Do you mean Portland, Oregon or Portland, Maine") and the user instead says "what's the weather", Bixby re-interprets the utterance and classifies it as a weather intent that is locked within the capsule. After the capsule lock expires, utterances are treated as "brand new" and will no longer be limited to the weather capsule.
If you are in a confirmation prompt, you can set the modal-prompt
key in the confirmation view to true
to ignore any off-topic responses and re-prompt for the confirmation.
If your capsule is on the Marketplace and you haven't used the result-view-capsule-lock
flag to opt out of capsule lock, conversation drivers in result views only display if the device itself also supports capsule lock.
You can opt out of capsule lock by overriding the result-view-capsule-lock
flag in your runtime version and setting it to false
. If you need to opt out of capsule lock only during specific result moments, you can use the capsule-lock
key in that particular result view.
If you do opt out of capsule lock, conversation drivers will still appear on the result view page, but they might not behave as expected. This is true even if the device does not support capsule lock.
Your capsules should take advantage of Bixby's personalization and learning abilities to minimize the number of prompts when possible. For example, when the user asks for the weather but doesn't specify a location, it's reasonable to assume they want the weather for their current area; a ride-sharing service capsule could remember that the user always asks for the cheapest available ride, and so might present that as its default choice. However, in some cases—especially involving actions that might lead to purchases, such as booking a ride or a hotel—your capsule should prompt the user for confirmation.
When Bixby does prompt users, though, you should ensure the prompts are clear, easily understood, and presented in the most logical order.
Make sure any text you write for Bixby follows the dialog best practices as well as the Writing Dialog design guidelines.
Bixby can generate default dialog for selection and value prompts, but you can refine its dialog by creating elicitation and selection dialog events.
An Elicitation Event generates dialog for a value prompt. The "I need a number of dice to continue" prompt message comes from the default template for a missing input with single value cardinality:
I need #{concept(this, 'Indefinite')} to continue.
You could provide your own dialog event for it to override the default:
dialog (Elicitation) {
match: NumDice
template("How many dice do you want to roll?")
}
A Selection Event generates dialog for a selection prompt. The default template for a selection is to present a concept fragment for the input's concept (see the dialog event reference for details). This template can also be overridden with a custom dialog event:
dialog (Selection) {
match : viv.email.EmailAddress (this)
// Which email address?
template("Which #{concept(this)}?")
}
This dialogue uses the concept
Expression Language formatting function to format viv.email.EmailAddress
as a concept fragment.
If Bixby needs to prompt for more than one piece of information during execution, the order is determined by the order of the input
blocks within the action's collect
block. For example, this is part of the RollDice
action from the Dice example capsule:
action (RollDice) {
collect{
input (numDice) {
type (NumDiceConcept)
min (Required)
max (One)
}
input (numSides) {
type (NumSidesConcept)
min (Required)
max (One)
}
}
output (RollResultConcept)
type (Calculation)
}
An utterance with no values, such as "Roll dice," will cause Bixby to prompt first for the number of dice and then the number of sides for the dice. An utterance missing only one value, such as "Roll 3 dice," will only cause one prompt.
The finished Dice capsule provides default values and validations for numDice
and numSides
, so in practice it will never prompt for values unless they fail their validations. You should use defaults and learning to minimize the number of prompts your capsule might ask.
By default, Bixby will not prompt the user unless a cardinality violation has occurred. There are some circumstances, however, in which you might might want to always prompt the user. For an example, the sample basic shopping cart capsule creates a shirt store. The shirt's Size
input should always be confirmed, even when the size is mentioned in the utterance. You can change prompting for a specific input through the prompt-behavior
key. To always confirm the shirt size, set prompt-behavior
on the size
input to AlwaysSelection
:
action (GetSize) {
type (Constructor)
collect {
input (size) {
type(Size)
min(Required)
max(One)
plan-behavior (Never)
prompt-behavior (AlwaysSelection)
//Lists all available options
default-init {
intent {
goal: Size
value-set: Size { Size(ExtraSmall) Size(Small) Size(Medium) Size(Large) Size(ExtraLarge) }
}
}
}
}
output (PromptedSize) {
evaluate { $expr(size) }
}
}
This setting ensures the user will always be prompted to either supply a missing value or confirm it. Typically, this is the only behavioral mode you will use in input
blocks other than default
, which will only prompt the user to supply values when there is a cardinality violation (there are no values supplied, or there are two or more values supplied for a max (One)
input).
As described in Implementing Delight Nuggets, Bixby offers three kinds of confirmation prompts:
As with selection and value prompts, you can override Bixby's defaults by supplying new templates for dialog events.
A Storage Event generates dialog for a persistence confirmation prompt, asking the user if they wish to store a value.
dialog (Storage) {
match: viv.payment.CreditCardPaymentSource (this)
template ("Would you like us to save this #{concept (this)} for future use?")
}
A Confirmation Event generates dialog for an action confirmation prompt, asking the user if they wish to proceed with an action.
dialog (Confirmation) {
match: viv.paymentService.MakePayment
template ("Ready to send?")
}
Actions can be set to explicitly require confirmation through the use of the confirm
key which calls an appropriate confirmation-view
that you create. You can use confirmation layouts to create more complex confirmations or to override the default layouts. If all you need to do is create a simple confirmation, you can choose to render nothing
.
For the more complex interactions, such as presenting a restaurant booking screen that lets the user verify and, if necessary, change the reservation date, time, and party size, you can render a layout within the confirmation view.
Bixby can also prompt a user to grant a capsule permission. Users can respond both by tapping "Yes" or "No", or by speaking a response. Permission prompts are not customizable.