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:
The label object
A label object represents an individual friendly name.
Label object details
| Field | Description | Type | Required |
|---|---|---|---|
@type |
The type of label. Valid values are asset and text. |
String | Yes |
value |
The value of the friendly name. | Object | Yes |
value.assetId |
An asset identifier from the global Alexa catalog. | String | Yes when @type is asset. |
value.text |
The text of the friendly name. | String | Yes when @type is text. |
value.locale |
The language and locale of the friendly name. | String | Yes when @type is text. |
Label object example with text label
{
"@type": "text",
"value": {
"text": "normal",
"locale": "en-US"
}
}
Label object example with non-en-US text label
{
"@type": "text",
"value": {
"text": "Capsules de café",
"locale": "fr-FR"
}
}
Label object example with asset label
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"
}
}
Capability resources
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: ModeController, RangeController, ToggleController, InventoryLevelSensor, InventoryUsageSensor.
Include the capabilityResources property in your Discover.Response event during the discovery process to provide friendly names.
Capability resources property details
| Field | Description | Type | Required |
|---|---|---|---|
friendlyNames |
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. | An array of label objects. | Yes |
Capability resources 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.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<a unique identifier, preferably a version 4 UUID>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Coffee Maker Plus",
"description": "Smart Coffee Maker by Coffee Maker Plus",
"friendlyName": "Coffee maker",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryUsageSensor",
"instance": "Sensor.CoffeePod",
"version": "3",
"configuration": {
"measurement": {
"@type": "Count"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Coffee pods",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Cápsulas de Café",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Capsules de café",
"locale": "fr-CA"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Mode resources
When you implement 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.
Mode resources property details
| Field | Description | Type | Required |
|---|---|---|---|
friendlyNames |
Friendly names that users can use to refer to a mode value when talking to Alexa. | An array of label objects. | Yes |
Mode resources 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
capabilityResourcesproperty so the user can refer to theWashCyclemode by different names. TheWashCyclemode contains two settings namedNormalandDelicates. - The response specifies friendly names in the
modeResourcesproperty 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. This example also provides friendly names in multiple languages.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Washer Maker Plus",
"description": "Smart Washer by Washer Maker Plus",
"friendlyName": "Washer",
"displayCategories": ["OTHER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true,
"nonControllable": false
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.WashCycle"
}
},
{
"@type": "text",
"value": {
"text": "wash cycle",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "wash setting",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Ciclo de lavado",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Cycle de lavage",
"locale": "fr-CA"
}
}
]
},
"configuration": {
"ordered": false,
"supportedModes": [
{
"value": "WashCycle.Normal",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "normal",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "cottons",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Ciclo normal",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Cycle délicat",
"locale": "fr-CA"
}
}
]
}
},
{
"value": "WashCycle.Delicates",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Delicate"
}
},
{
"@type": "text",
"value": {
"text": "Delicates",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Knits",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Ciclo delicado",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Cycle délicat",
"locale": "fr-CA"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Preset resources
When you implement 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.
Preset resources property details
| Field | Description | Type | Required |
|---|---|---|---|
friendlyNames |
Friendly names that users can use to refer to preset range values when talking to Alexa. | An array of label objects. | Yes |
Preset resources 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
capabilityResourcesproperty so the user can refer to the fan speed range by different names. - The response specifies friendly names in the
presetResourcesproperty 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.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<description that appears in the Alexa app>",
"friendlyName": "<device name that appears in the Alexa app>",
"displayCategories": ["FAN"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.RangeController",
"instance": "Fan.Speed",
"version": "3",
"properties": {
"supported": [
{
"name": "rangeValue"
}
],
"proactivelyReported": true,
"retrievable": true,
"nonControllable": false
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.FanSpeed"
}
}
]
},
"configuration": {
"supportedRange": {
"minimumValue": 1,
"maximumValue": 10,
"precision": 1
},
"presets": [
{
"rangeValue": 10,
"presetResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Maximum"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.High"
}
},
{
"@type": "text",
"value": {
"text": "Highest",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Fast",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Alta",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Élevée",
"locale": "fr-CA"
}
}
]
}
},
{
"rangeValue": 1,
"presetResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Minimum"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Low"
}
},
{
"@type": "text",
"value": {
"text": "Lowest",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Slow",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Baja",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Faible",
"locale": "fr-CA"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
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 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 |
|---|---|
| Alexa.DeviceName.AirPurifier | Air Purifier, Air Cleaner, Clean Air Machine |
| Alexa.DeviceName.Camera | Camera |
| Alexa.DeviceName.Fan | Fan, Blower |
| Alexa.DeviceName.Router | Router, Internet Router, Network Router, Wi-Fi Router, Net Router |
| Alexa.DeviceName.Shade | Shade, Blind, Curtain, Roller, Shutter, Drape, Awning, Window shade, Interior blind |
| Alexa.DeviceName.Shower | Shower |
| Alexa.DeviceName.SpaceHeater | Space Heater, Portable Heater |
| Alexa.DeviceName.Washer | Washer, Washing Machine |
| Alexa.Setting.2GGuestWiFi | 2.4G Guest Wi-Fi, 2.4G Guest Network, Guest Network 2.4G, 2G Guest Wi-Fi |
| Alexa.Setting.5GGuestWiFi | 5G Guest Wi-Fi, 5G Guest Network, Guest Network 5G, 5G Guest Wi-Fi |
| Alexa.Setting.Auto | Auto, Automatic, Automatic Mode, Auto Mode |
| Alexa.Setting.Direction | Direction |
| Alexa.Setting.DryCycle | Dry Cycle, Dry Preset, Dry Setting, Dryer Cycle, Dryer Preset, Dryer Setting |
| Alexa.Setting.FanSpeed | Fan Speed, Airflow speed, Wind Speed, Air speed, Air velocity |
| Alexa.Setting.GuestWiFi | Guest Wi-Fi, Guest Network, Guest Net |
| Alexa.Setting.Heat | Heat |
| Alexa.Setting.Mode | Mode |
| Alexa.Setting.Night | Night, Night Mode |
| Alexa.Setting.Opening | Opening, Height, Lift, Width |
| Alexa.Setting.Oscillate | Oscillate, Swivel, Oscillation, Spin, Back and forth |
| Alexa.Setting.Preset | Preset, Setting |
| Alexa.Setting.Quiet | Quiet, Quiet Mode, Noiseless, Silent |
| Alexa.Setting.Temperature | Temperature, Temp |
| Alexa.Setting.WashCycle | Wash Cycle, Wash Preset, Wash setting |
| Alexa.Setting.WaterTemperature | Water Temperature, Water Temp, Water Heat |
| Alexa.Shower.HandHeld | Handheld, Handheld Shower, Shower Wand, Hand Shower |
| Alexa.Shower.RainHead | Rain Head, Overhead shower, Rain Shower, Rain Spout, Rain Faucet |
| Alexa.Unit.Angle.Degrees | Degrees, Degree |
| Alexa.Unit.Angle.Radians | Radians, Radian |
| Alexa.Unit.Distance.Feet | Feet, Foot |
| Alexa.Unit.Distance.Inches | Inches, Inch |
| Alexa.Unit.Distance.Kilometers | Kilometers |
| Alexa.Unit.Distance.Meters | Meters, Meter, m |
| Alexa.Unit.Distance.Miles | Miles, Mile |
| Alexa.Unit.Distance.Yards | Yards, Yard |
| Alexa.Unit.Mass.Grams | Grams, Gram, g |
| Alexa.Unit.Mass.Kilograms | Kilograms, Kilogram, kg |
| Alexa.Unit.Percent | Percent |
| Alexa.Unit.Temperature.Celsius | Celsius, Degrees Celsius, Degrees, C, Centigrade, Degrees Centigrade |
| Alexa.Unit.Temperature.Degrees | Degrees, Degree |
| Alexa.Unit.Temperature.Fahrenheit | Fahrenheit, Degrees Fahrenheit, Degrees F, Degrees, F |
| Alexa.Unit.Temperature.Kelvin | Kelvin, Degrees Kelvin, Degrees K, Degrees, K |
| Alexa.Unit.Volume.CubicFeet | Cubic Feet, Cubic Foot |
| Alexa.Unit.Volume.CubicMeters | Cubic Meters, Cubic Meter, Meters Cubed |
| Alexa.Unit.Volume.Gallons | Gallons, Gallon |
| Alexa.Unit.Volume.Liters | Liters, Liter, L |
| Alexa.Unit.Volume.Pints | Pints, Pint |
| Alexa.Unit.Volume.Quarts | Quarts, Quart |
| Alexa.Unit.Weight.Ounces | Ounces, Ounce, oz |
| Alexa.Unit.Weight.Pounds | Pounds, Pound, lbs |
| Alexa.Value.Close | Close |
| Alexa.Value.Delicate | Delicates, Delicate |
| Alexa.Value.High | High |
| Alexa.Value.Low | Low |
| Alexa.Value.Maximum | Maximum, Max |
| Alexa.Value.Medium | Medium, Mid |
| Alexa.Value.Minimum | Minimum, Min |
| Alexa.Value.Open | Open |
| Alexa.Value.QuickWash | 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.