Friendly Name Resources and Assets

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

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.

Important: Users can refer to any of your friendly names when speaking to Alexa, but the first friendly name is the name that appears in the Alexa app.

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:

Capability resources friendly names
Mode resources friendly names
Preset resources friendly names

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

Copied to clipboard.

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

Text label in French example

Copied to clipboard.

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

Copied to clipboard.

{
    "@type": "asset",
    "value": {
        "assetId": "Alexa.Setting.Quiet"
    }
}

Label object details

Property	Description	Type	Required
`@type`	The type of label. Valid values: `asset`, `text`	String	Yes
`value`	The value of the friendly name.	Object	Yes
`value.assetId`	An asset identifier from the global Alexa catalog. Required for `@type` = `asset`.	String	No
`value.text`	The text of the friendly name. Required for `@type` = `text`.	String	No
`value.locale`	The language and locale of the friendly name. Required for `@type` = `text`.	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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "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": "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"
            }
          ]
        }
      ]
    }
  }
}

CapabilityResources property details

Property	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.	Array of `Label` objects	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 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 and provides friendly names in multiple languages.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "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"
            }
          ]
        }
      ]
    }
  }
}

ModeResources property details

Property	Description	Type	Required
`friendlyNames`	Friendly names that users can use to refer to a mode value when talking to Alexa.	Array of `Label` objects	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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Your device name, displayed 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"
            }
          ]
        }
      ]
    }
  }
}

PresetResources property details

Property	Description	Type	Required
`friendlyNames`	Friendly names that users can use to refer to preset range values when talking to Alexa.	Array of `Label` objects	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 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.

Important: The global Alexa catalog is localized into all the languages that Alexa supports.

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.

Note: The ability to upload your own catalog is coming soon.

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.

Friendly Name Resources and Assets

Label object

Text label example

Text label in French example

Asset label example

Label object details

CapabilityResources object

CapabilityResources example

CapabilityResources property details

ModeResources property

ModeResources example

ModeResources property details

PresetResources property

PresetResources example

PresetResources property details

Global Alexa catalog

Upload your own catalog

Reserved words

Related topics