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 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

Copied to clipboard.

{
    "@type": "text",
    "value": {
        "text": "normal",
        "locale": "en-US"
    }
}

Label object example with non-en-US text label

Copied to clipboard.

{
    "@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".

Copied to clipboard.

{
    "@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.

Copied to clipboard.

{
  "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 capabilityResources property so the user can refer to the WashCycle mode by different names. The WashCycle mode contains two settings named Normal and Delicates.
  • 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. This example also provides friendly names in multiple languages.

Copied to clipboard.

{
  "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": "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 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.

Copied to clipboard.

{
  "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": "<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.