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
- Label object
- CapabilityResources
- PresetResources
- Global Alexa catalog
- Upload your own catalog
- Names you cannot use
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
@type field to identify the object type, and provide the values required for that type.| 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"
}
}
]
}
}
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.