Friendly Name Resources and Assets
To give your users more flexibility in how they speak to Alexa when they use your skill or device, you can provide multiple friendly names for some capabilities. For example, if your device is a washing machine with a default wash cycle, you can provide multiple friendly names so that users can say "Alexa, set the wash cycle to normal" or "Alexa, set the wash cycle to cottons." You can also use friendly names to provide access to your skill or device in multiple languages.
You can provide friendly names in the following ways:
- You can specify your own friendly names as text.
- You can use friendly names from the global Alexa catalog.
- You can upload your own catalog of friendly names.
You provide friendly names in your Discover.Response
event during the discovery process, as described in the following sections:
Label object
A Label
object represents an individual friendly name. You can define the name or use a name from the global Alexa catalog.
Text label example
{
"@type": "text",
"value": {
"text": "normal",
"locale": "en-US"
}
}
Text label in French example
{
"@type": "text",
"value": {
"text": "Capsules de café",
"locale": "fr-FR"
}
}
Asset label example
The following example contains an asset label for a friendly name. This example uses the Alexa.Setting.Quiet
asset so that users can say any of the following to Alexa: "Quiet", "Quiet Mode", "Noiseless", "Silent".
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.Quiet"
}
}
Label object details
Property | Description | Type | Required |
---|---|---|---|
|
The type of label. |
String |
Yes |
|
The value of the friendly name. |
Object |
Yes |
|
An asset identifier from the global Alexa catalog. Required for |
String |
No |
|
The text of the friendly name. Required for |
String |
No |
|
The language and locale of the friendly name. |
String |
No |
CapabilityResources object
When you implement some interfaces, especially interfaces that you can implement multiple times for the same device, you can give the different interface instances friendly names. Examples include the following interfaces: Alexa.ModeController
, Alexa.RangeController
, Alexa.ToggleController
, Alexa.InventoryLevelSensor
, Alexa.InventoryUsageSensor
.
Include the CapabilityResources
object in your Discover.Response
event during the discovery process to provide friendly names.
CapabilityResources example
The following example shows a Discover.Response
message for a coffee maker that supports the Alexa.InventoryUsageSensor
interface for tracking coffee pod usage. The response specifies friendly names so the user can refer to the sensor as "Coffee pods". This example also provides friendly names in multiple languages.
CapabilityResources property details
Property | Description | Type | Required |
---|---|---|---|
|
Friendly names that users can use to refer to an interface instance when talking to Alexa. The first friendly name in the array must be unique for the endpoint. |
Array of |
Yes |
ModeResources property
When you implement Alexa.ModeController
, use mode resources to provide friendly names for the supported modes. Include the modeResources
property in your Discover.Response
event during the discovery process to provide friendly names.
ModeResources example
The following example shows a Discover.Response
message for a washing machine that supports the Alexa.ModeController
interface. This example contains one mode named WashCycle
. The response specifies multiple sets of friendly names:
- The response specifies friendly names in the
capabilityResources
property so the user can refer to theWashCycle
mode by different names. TheWashCycle
mode contains two settings namedNormal
andDelicates
. - The response specifies friendly names in the
modeResources
property so the user can refer to the mode settings by different names. The user can say phrases like "Alexa, set the wash setting to knits."
This example uses assets from the global Alexa catalog and provides friendly names in multiple languages.
ModeResources property details
Property | Description | Type | Required |
---|---|---|---|
|
Friendly names that users can use to refer to a mode value when talking to Alexa. |
Array of |
Yes |
PresetResources property
When you implement Alexa.RangeController
, use preset resources to provide friendly names for supported preset range values. Include the presetResources
property in your Discover.Response
event during the discovery process to provide friendly names.
PresetResources example
The following example shows a Discover.Response
message for a fan that supports the Alexa.RangeController
interface. This example contains one range named Fan.Speed
. The response specifies multiple sets of friendly names:
- The response specifies friendly names in the
capabilityResources
property so the user can refer to the fan speed range by different names. - The response specifies friendly names in the
presetResources
property so the user can refer to the fastest and slowest fan speeds by different names. The user can say phrases like "Alexa, set the fan speed to slow."
This example uses assets from the global Alexa catalog. This example also provides friendly names in multiple languages.
PresetResources property details
Property | Description | Type | Required |
---|---|---|---|
|
Friendly names that users can use to refer to preset range values when talking to Alexa. |
Array of |
Yes |
Global Alexa catalog
You can use the global Alexa catalog of pre-defined friendly names in your skills. Each item in the catalog is an asset identifier that supports one or more friendly names. For each asset identifier that you specify in your skill, your users get access to multiple friendly names. The first friendly name in the table is the name that appears in the Alexa app.
Asset identifiers use a namespace to identify the source catalog for their values. The Alexa
namespace indicates the global catalog curated by Amazon.
Asset identifier | Supported friendly names |
---|---|
|
Off button |
|
On button |
|
Brighten button |
|
Dim button |
|
Main button |
|
Top button |
|
Bottom button |
|
Center button |
|
Middle button |
|
Up button |
|
Down button |
|
Left button |
|
Right button |
|
First button |
|
Second button |
|
Third button |
|
Fourth button |
|
Fifth button |
|
Sixth button |
|
Seventh button |
|
Eighth button |
|
Double press |
|
Double push |
|
Long press |
|
Long push |
|
Single press |
|
Single push |
|
Air Purifier, Air Cleaner, Clean Air Machine |
|
Camera |
|
Fan, Blower |
|
Router, Internet Router, Network Router, Wi-Fi Router, Net Router |
|
Shade, Blind, Curtain, Roller, Shutter, Drape, Awning, Window shade, Interior blind |
|
Shower |
|
Space Heater, Portable Heater |
|
Washer, Washing Machine |
|
Double click |
|
Double tap |
|
Single click |
|
Swipe down |
|
Swipe left |
|
Swipe right |
|
Swipe up |
|
Tap |
|
2.4G Guest Wi-Fi, 2.4G Guest Network, Guest Network 2.4G, 2G Guest Wi-Fi |
|
5G Guest Wi-Fi, 5G Guest Network, Guest Network 5G, 5G Guest Wi-Fi |
|
Auto, Automatic, Automatic Mode, Auto Mode |
|
Direction |
|
Dry Cycle, Dry Preset, Dry Setting, Dryer Cycle, Dryer Preset, Dryer Setting |
|
Fan Speed, Airflow speed, Wind Speed, Air speed, Air velocity |
|
Guest Wi-Fi, Guest Network, Guest Net |
|
Heat |
|
Mode |
|
Night, Night Mode |
|
Opening, Height, Lift, Width |
|
Oscillate, Swivel, Oscillation, Spin, Back and forth |
|
Preset, Setting |
|
Quiet, Quiet Mode, Noiseless, Silent |
|
Temperature, Temp |
|
Wash Cycle, Wash Preset, Wash setting |
|
Water Temperature, Water Temp, Water Heat |
|
Handheld, Handheld Shower, Shower Wand, Hand Shower |
|
Rain Head, Overhead shower, Rain Shower, Rain Spout, Rain Faucet |
|
Degrees, Degree |
|
Radians, Radian |
|
Feet, Foot |
|
Inches, Inch |
|
Kilometers |
|
Meters, Meter, m |
|
Miles, Mile |
|
Yards, Yard |
|
Grams, Gram, g |
|
Kilograms, Kilogram, kg |
|
Percent |
|
Celsius, Degrees Celsius, Degrees, C, Centigrade, Degrees Centigrade |
|
Degrees, Degree |
|
Fahrenheit, Degrees Fahrenheit, Degrees F, Degrees, F |
|
Kelvin, Degrees Kelvin, Degrees K, Degrees, K |
|
Cubic Feet, Cubic Foot |
|
Cubic Meters, Cubic Meter, Meters Cubed |
|
Gallons, Gallon |
|
Liters, Liter, L |
|
Pints, Pint |
|
Quarts, Quart |
|
Ounces, Ounce, oz |
|
Pounds, Pound, lbs |
|
Close |
|
Delicates, Delicate |
|
High |
|
Low |
|
Maximum, Max |
|
Medium, Mid |
|
Minimum, Min |
|
Open |
|
Quick Wash, Fast Wash, Wash Quickly, Speed Wash |
Upload your own catalog
You can upload your own catalog with your own custom terms.
Amazon recommends that you use a catalog for friendly names that require localization. For user-defined names and settings, use plain text strings and notify Alexa of any changes in an AddOrUpdateReport
.
Reserved words
Don't use any of the following reserved words as friendly names:
alarm, alarms, all alarms, away mode, bass, camera, date, date today, day, do not disturb, drop in, music, night light, notification, playing, sleep sounds, time, timer, today in music, treble, volume, way f. m.
Related topics
Last updated: Nov 22, 2023