Resources and Assets

To give customers more flexibility in how they speak, you can provide multiple friendly names for some capabilities or their configurations. You provide these friendly names through Resources objects. Customers can use any of the provided friendly names when speaking to Alexa. The first entry in the list is considered primary and is displayed in the Alexa app.

Resources objects

The following table describes the fields in capabilityResources, ModeResources, and presetResources objects.

Field Description Type
friendlyNames Required. An array of Label objects that customers can use for VUI and GUI interactions. The first label in the list is the primary name and is used for display in the GUI. The primary name must be unique for the endpoint. All the labels in the list are synonyms and are valid for targeting a device with VUI interactions. array of Label objects

Label object

Resources are made up of label objects. You can use labels from the global Alexa catalog, or you can upload your own catalog of labels.

The following tables describe the fields in a label object in more detail.

Label object

Field Type Description
@type string Required. The type of the object. Supported values are asset and text.
value object Required. The value of the label.

When @type is asset, contains an AssetString that references an item from a localized catalog of strings.

When @type is text, contains a TextString to represent a literal string value.

AssetString object

Field Type Description
assetId string Required. The ID of the localized string in the global or skill catalog.

TextString object

Field Type Description
text string Required. The literal representation of a string.
locale string Required. The locale in which the string is localized. Currently, the only supported value is en-US.

Assets use a namespace to identify the source catalog for their values. The Alexa namespace indicates the global catalog curated by Amazon. Other namespaces indicate vendor catalogs, and can be prefaced with the name of the catalog associated with the device, or with the My prefix to indicate a vendor catalog.

CapabilityResources

Use capabilityResources to provide a set of friendlyNames for the ToggleController, RangeController, and ModeController interfaces.

Example capabilityResources

The following example shows one way to model a fan with a "rotate" feature. The skill uses an Alexa.ToggleController and provides friendlyNames of "Rotate" and "Rotation" as plain text. This allows customers to say phrases like "Turn on rotate on the fan" or "Enable fan rotation". The skill also uses an asset of Alexa.Setting.Oscillate as an alternate, so customers can use words like oscillate, oscillation, swivel, and others defined in the Alexa.Setting.Oscillate catalog.

In the following example the first friendly name ("Rotate") is the one displayed in the Alexa mobile app. The friendly name listed first is the one displayed in the app.

{
  "type": "AlexaInterface",
  "interface": "Alexa.ToggleController",
  "version": "3",
  "instance": "SampleFan.Rotate",
  "capabilityResources": {
    "friendlyNames": [
      {
        "@type": "text",
        "value": {
          "text": "Rotate",
          "locale": "en-US"
        }
      },
      {
        "@type": "text",
        "value": {
          "text": "Rotation",
          "locale": "en-US"
        }
      },
      {
        "@type": "asset",
        "value": {
          "assetId": "Alexa.Setting.Oscillate"
        }
      }
    ]
  }
}

ModeResources

Use modeResources with ModeController to provide a set of friendlyNames for each supported mode.

Example modeResources

The following example shows one way to model a fan that has three modes: "normal", "auto", and "night mode". The skill models this feature with an Alexa.ModeController and provides friendlyNames for each of the supportedModes. The skill provides friendlyNames for night mode of Alexa.Setting.Night as an asset, and "White Noise" as plain text. This allows customers to say phrases like "Set the fan speed to night mode" or "Set the fan to white noise".

In the following example the first friendly name ("Night", which is the first friendly name for the Alexa.Setting.Night identifier) is the one displayed in the Alexa mobile app. The friendly name listed first is the one displayed in the app.

{
  "supportedModes": [
    {
      "value": "SampleFanMode.Night",
      "modeResources": {
        "friendlyNames": [
          {
            "@type": "asset",
            "value": {
              "assetId": "Alexa.Setting.Night"
            }
          },
          {
            "@type": "text",
            "value": {
              "text": "White Noise",
              "locale": "en-US"
            }
          }
        ]
      }
    }
  ]
}

PresetResources

Use presetResources with RangeController to provide a set of friendlyNames for each RangeController preset.

Example presetResources

The following example shows one way to model a fan that has a speed feature. The skill models this feature with an Alexa.RangeController and provides presets for various range values. This allows customers to set the fan speed to a numeric value without using a number in their utterance. For example, the skill provides a preset for 1 with friendlyNames of Alexa.Value.Low as an asset, and "Slowest" as plain text. This allows customers to say phrases like "Set the fan speed to low" or "Set the fan speed to slowest".

In the following example the first friendly name ("Low", which is the first friendly name for the Alexa.Value.Low identifier) is the one displayed in the Alexa mobile app. The friendly name listed first is the one displayed in the app.

{
  "presets": [
    {
      "rangeValue": 1,
      "presetResources": {
        "friendlyNames": [
          {
            "@type": "asset",
            "value": {
              "assetId": "Alexa.Value.Low"
            }
          },
          {
            "@type": "text",
            "value": {
              "text": "Slowest",
              "locale": "en-US"
            }
          }
        ]
      }
    }
  ]
}

Global Alexa catalog

You can use the global Alexa catalog for pre-defined names of devices, settings, values, and units. This catalog is localized into all the languages that Alexa supports.

You can reference the following catalog of pre-defined friendly names. Each item in the following list is an asset identifier followed by its supported friendly names. The first friendly name for each identifier (in bold) is the one displayed in the Alexa mobile app.

Asset Identifier Supported Friendly Names
Alexa.DeviceName.Shower Shower
Alexa.DeviceName.Washer Washer
Washing Machine
Alexa.DeviceName.Router Router
Internet Router
Network Router
Wifi Router
Net Router
Alexa.DeviceName.Fan Fan
Blower
Alexa.DeviceName.AirPurifier Air Purifier
Air Cleaner
Clean Air Machine
Alexa.DeviceName.SpaceHeater Space Heater
Portable Heater
Alexa.Shower.RainHead Rain Head
Overhead shower
Rain Shower
Rain Spout
Rain Faucet
Alexa.Shower.HandHeld Handheld Shower
Shower Wand
Hand Shower
Alexa.Setting.WaterTemperature Water Temperature
Water Temp
Water Heat
Alexa.Setting.Temperature Temperature
Temp
Alexa.Setting.WashCycle Wash Cycle
Wash Preset
Wash setting
Alexa.Setting.2GGuestWiFi 2.4G Guest Wi-Fi
2.4G Guest Network
Guest Network 2.4G
2G Guest Wifi
Alexa.Setting.5GGuestWiFi 5G Guest Wi-Fi
5G Guest Network
Guest Network 5G
5G Guest Wifi
Alexa.Setting.GuestWiFi Guest Wi-fi
Guest Network
Guest Net
Alexa.Setting.Auto Auto
Automatic
Automatic Mode
Auto Mode
Alexa.Setting.Night Night
Night Mode
Alexa.Setting.Quiet Quiet
Quiet Mode
Noiseless
Silent
Alexa.Setting.Oscillate Oscillate
Swivel
Oscillation
Spin
Back and forth
Alexa.Setting.FanSpeed Fan Speed
Airflow speed
Wind Speed
Air speed
Air velocity
Alexa.Setting.Preset Preset
Setting
Alexa.Setting.Mode Mode
Alexa.Setting.Direction Direction
Alexa.Value.Delicate Delicates
Delicate
Alexa.Value.QuickWash Quick Wash
Fast Wash
Wash Quickly
Speed Wash
Alexa.Value.Maximum Maximum
Max
Alexa.Value.Minimum Minimum
Min
Alexa.Value.High High
Alexa.Value.Low Low
Alexa.Value.Medium Medium
Mid

Upload your own catalog

You can also upload your own catalog with your own custom terms.

We recommend that you use catalogs for any names that require localization. For user-defined names and settings, we recommend that you use plain text strings and notify Alexa of any changes via an AddOrUpdateReport.

Names you cannot use

You cannot use any friendly names from the following list:

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