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:

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.

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.

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.

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.

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.