Bixby Developer Center

Guides
References

hints

required

Top-level declaration of hints. Hints are used by Bixby to provide users with suggested queries. Hints consist of a named dispatch phrase and a suggested utterance. All hints must have a dispatch phrase associated with them to ensure that they go to the correct capsule.

You can add a preferred-hint to an existing hint, for instances when named dispatch isn't needed, such as if your capsule is the default for an NL category. You should add a preferred-hint if your hint does not make sense grammatically without the dispatch phrase. In the cases where the dispatch phrase is dropped, the first letter of the utterance is capitalized. For example, "Ask ACME Media Player to play my summer playlist" becomes "Play my summer playlist".

You can sort the hints by the capsule's category. For example, if you have a media playing capsule, you might use a set of hints with for-category (Radio) and another set with for-category (Podcast). If there are any hints you need to add that are not related to a specific category, you can place them in uncategorized. For more information, see Categorizing Hints.

You can also provide multiple hint groups within a single hints.bxb file, which is especially useful if you need different visibility-constraints. For example, if your capsule is available in the Marketplace, targets en as a locale, but has different NL categories depending on the country store, you can have a single resources/en/hints.bxb file with similar visibility constraints as your NL categories. Another example is using target-constraints to separate hints by regional vocabulary.

If you add visibility contraints to your hints though, this might affect the total visible number of hints you need to submit to Marketplace. For example, if you have a capsule for mobile and watch, but mobile targets the US in English and Korean store countries in Korean, while the watch target is only for en-US, you need to make sure you have 3 hints visible and working for mobile in English, 3 hints visible and working for mobile in Korean, and 3 hints visible and working for watch in English. You can choose to do this in several ways. For example, you can create separate help files for each subset of the Marketplace you want to support, or you can have a single hints file without any restrictions that shows up in all store countries.

You must provide at least three uncategorized, visible hints that work when submitting to the Marketplace for each store country and device. For more information, see Provide Hints for Bixby.

Note

If you are planning to localize your capsule, create a separate hints.bxb file for each locale your capsule is supporting.

You must define this top-level key and its child keys in a *.hints.bxb or hints.bxb file. This file must be in the appropriate locale-specific resources folder.

Examples

Hints file with NL categories and uncategorized hints:

// resources/en/my_hints.hints.bxb
hints {
for-category (Radio) {
hint ("In ACME Media Player, play some classical music")
hint ("Ask ACME Media Player to play my local hip-hop station")
hint ("With ACME Media Player, play KMEL")
}

for-category (Podcast) {
hint ("In ACME Media Player, play the newest episode of philosophize this")
hint ("Ask ACME Media Player for my favorite podcast")
hint ("Ask ACME Media Player to play an episode of rewatching")
}

uncategorized {
hint ("In ACME Media Player, tell me a story")
hint ("Ask ACME Media Player to start something interesting")
hint ("With ACME Media Player, play something relaxing")
}
}

Hints file with only uncategorized hints, in English and in Korean:

hints {
uncategorized {
hint (In Space Resorts, find space resorts)
hint (With Space Resorts, find hotels near Mars)
hint (In Space Resorts, research space resorts on Mercury)
}
}

View on GitHub

hints {
uncategorized {
hint (스페이스 리조트에서 금성에 무중력 골프장이 있는 리조트 보여줘봐)
hint (스페이스 리조트 열어서 해왕성에 키즈룸이 있는 호텔 찾아봐)
hint (스페이스 리조트에서 토성 근처 리조트 검색해줘)
}
}

View on GitHub

Separating hints by regional vocabulary using target-constraints:

// For US stores
hints {
visibility-constraints {
target-constraints {
allowed-list {
allow (en-US)
}
}
}
uncategorized {
hint ("Ask ACME Smart Helper to find my garage keys"){
preferred-hint ("Find my garage keys")
}
hint ("Ask ACME Smart Helper to start the car")
hint ("In ACME Smart Helper, turn on the lights") {
preferred-hint ("Turn on the lights)
}
}
}
hints {
visibility-constraints {
target-constraints {
allowed-list {
allow (en-GB)
}
}
uncategorized {
hint ("Ask ACME Smart Helper to find my car parks keys"){
preferred-hint ("Find my car park keys")
}
hint ("Ask ACME Smart Helper to start the car")
hint ("In ACME Smart Helper, turn on the lights") {
preferred-hint ("Turn on the lights)
}
}
}

Categorizing Hints

If you choose to put your capsule in one or more NL Categories, you should make sure that each NL category has at least three working hints, as well as three uncategorized hints. Because users don't need named dispatch to use your capsule if they choose to make it a default, you should add a preferred-hint to make sure the hint makes sense without it.

Here is a working example of the "My Japanese Dictionary" capsule, which is part of the Translators NL category.

hints {
for-category (Translators) {
hint ("Ask My Japanese Dictionary what is artificial intelligence in Japanese?") {
preferred-hint ("What is artificial intelligence in Japanese?")
}
hint ("Ask My Japanese Dictionary what is alligator?") {
preferred-hint ("What is alligator in Japanese?")
}
hint ("Ask My Japanese Dictionary what is crab?") {
preferred-hint ("What is crab in Japanese?")
}
hint ("Ask My Japanese Dictionary what is the character for fire?") {
preferred-hint ("What is the character for fire in Japanese?")
}
}
uncategorized {
hint ("Look up teacher with My Japanese Dictionary")
hint ("Character for rain in My Japanese Dictionary ")
hint ("Look up a word with My Japanese Dictionary ")
hint ("Look up a character with My Japanese Dictionary ")
}
}

The categorized hints are displayed by default:

Uncategorized hints, capsule home page

If users go to see all the hints, they see the categorized hints with named dispatch under each NL category and uncategorized hints under "Others":

Hints page

When a user adds your capsules as the default for an NL category, the capsule home page and the hints page will not include the dispatch name. If you specify a preferred-hint, that hint text will show instead:

Uncategorized hints, capsule home page Uncategorized then categorized

Note

Categorized hints are not required. If you put your capsule in an NL category, but do not put any hints under that respective for-category, your hints will not be sorted:

Capsule Home Page, no for-category Hints page with no for-category

Child Keys

for-category
optional
Defines a set of hints for a particular NL category
uncategorized
optional
Defines a set of hints that don't correspond to any capsule category
visibility-constraints
optional
Collection of constraints for the given entry