Alexa.ModeController Interface
Implement the Alexa.ModeController interface in your Alexa skill so that users can control the mode settings of a device. You can use the ModeController interface to model properties of a device that the user can set to one of a list of values, such as the wash cycle mode of a washing machine. The list of values can have an order, but that's not required. The ModeController interface is a generic controller interface.
The ModeController interface is highly configurable and enables you to model many different kinds of settings for many different kinds of devices. Use one of the following more specific interfaces if it's appropriate for your device:
- Alexa.Cooking and CookingMode
- Alexa.EqualizerController and equalizer mode
- Alexa.LockController and LockState
- Alexa.ThermostatController and ThermostatMode
For the list of languages that the ModeController interface supports, see List of Alexa Interfaces and Supported Languages.
en-US only.Utterances
When you use the Alexa.ModeController interface, the voice interaction model is already built for you. The following examples show some user utterances:
Alexa, what's the wash setting on the washer?
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
Alexa, increase the water temperature on the washer.
You can enable additional utterances by using semantics. The following examples show user utterances enabled with semantics:
Alexa, open the garage door.
Alexa, close the garage door.
Alexa, raise the bedroom blinds.
Alexa, lower the living room blinds.
Alexa, fahre das Rollo in der Küche hoch.
Alexa, fahre die Rollläden im Wohnzimmer runter.
After the user says an utterance, Alexa sends a corresponding directive to your skill.
Properties and objects
The mode property
The Alexa.ModeController interface uses the mode property as the primary property. The property values are strings.
An endpoint can support multiple modes. To distinguish modes, you must always include the instance attribute for a mode property. You identify your instance names in your discovery response.
Mode property example
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Cold"
}
The mode object
The mode object represents an acceptable value for a mode.
Mode object details
| Field | Description | Type |
|---|---|---|
value |
The name of the mode value. | String |
modeResources |
Friendly names that users can use to interact with the mode value. | A modeResources object. |
Mode object example
The following example shows two mode objects in a supportedModes array.
"supportedModes": [
{
"value": "WashCycle.Normal",
"modeResources": {
}
},
{
"value": "WashCycle.Delicates",
"modeResources": {
}
}
]
The modeResources object
Use the modeResources object to provide a set of friendly names that users can use to interact with mode values. The first friendly name is the name that appears in the Alexa app. For details, see Resources and Assets.
ModeResources object example
The following example shows the mode resources for the delicate wash cycle of a washing machine. Users can say phrases like "Alexa, set the wash cycle to knits."
"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"
}
}
]
}
Semantics
Use semantics to enable additional features, such as additional user utterances and announcements when your device requires attention. To use semantics, include a semantics object in your discover response as described in the discovery section.
Use semantics to enable additional utterances
When you use the Alexa.ModeController interface, the voice interaction model is already built for you. Users can interact with your device by saying the standard ModeController utterances. For details, see utterances.
You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to the ModeController directives SetMode and AdjustMode. For example, if you have a controller for a garage door opener, you can map the phrase "open" to the SetMode directive.
open on a ModeController instance, you can't map the phrase open on any other ModeController instances, any RangeController instances, or any ToggleController instances.Use semantics to enable announcements
You can use semantics to enable announcements to the user when your device requires attention. For example, Alexa can notify a user when their automatic vacuum cleaner gets stuck. Notifications to the user take the form, Your <instance friendly name> is <state>.
To enable announcements, implement the ProactiveNotificationSource interface in your Alexa skill. To indicate the states that you support, include a semantics object in your discovery response to map the mode property to one of the Alexa.States values, such as Alexa.States.Empty. You trigger announcements by sending ChangeReport to report a change in the device state. For details, see ProactiveNotificationSource.
Discovery
You describe endpoints that support Alexa.ModeController using the standard discovery mechanism described in Alexa.Discovery.
Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.
You can model properties of an endpoint that users can't change by setting nonControllable to true. For example, when a washing machine automatically goes from wash, to rinse, to spin, you can report the current wash cycle to the user without allowing them to change it.
For each ModeController entry in the capabilities array, you can optionally include a semantics object. For details, see use semantics to enable additional utterances and use semantics to enable announcements.
For the full list of display categories, see display categories.
In addition to the usual discovery response fields, for each ModeController entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
The name of the mode, for example Washer.WashCycle or Washer.WashTemperature. |
String |
capabilityResources |
Friendly names that users can use to interact with the mode. If you enable announcements for the instance friendly name, include @type set to text. |
A CapabilityResources object. |
configuration.ordered |
True if the mode values have an order; otherwise, false. For example, a wash temperature mode could have values ordered from cold, to warm, to hot. Modes that have an order support the AdjustMode directive. |
Boolean |
configuration.supportedModes |
Specifies the list of accepted mode values. You must include a minimum of two mode objects. List ordered mode values in increasing order in the array. |
An array of mode objects. |
Discover response examples
Example
The following example shows a Discover.Response message for a washing machine that supports the Alexa.ModeController interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "Washer Maker Plus",
"description": "Smart Washer by Washer Maker Plus",
"friendlyName": "Washer",
"displayCategories": ["OTHER"],
"additionalAttributes": {
"manufacturer" : "Washer Maker Plus",
"model" : "Sample Model",
"serialNumber": "the serial number of the washer",
"customIdentifier": "your custom identifier for the washer"
},
"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": "Cycle",
"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.ModeController",
"instance": "Washer.CurrentWashCycle",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true,
"nonControllable": true
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Current wash cycle",
"locale": "en-US"
}
}
]
},
"configuration": {
"ordered": false,
"supportedModes": [
{
"value": "CurrentWashCycle.Wash",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Wash",
"locale": "en-US"
}
}
]
}
},
{
"value": "CurrentWashCycle.Rinse",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Rinse",
"locale": "en-US"
}
}
]
}
},
{
"value": "CurrentWashCycle.Spin",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Spin",
"locale": "en-US"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true,
"nonControllable": false
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.WaterTemperature"
}
},
{
"@type": "text",
"value": {
"text": "Wash temperature",
"locale": "en-US"
}
}
]
},
"configuration": {
"ordered": true,
"supportedModes": [
{
"value": "WashTemperature.Cold",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Cold",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Cool",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Fría",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Froide",
"locale": "fr-CA"
}
}
]
}
},
{
"value": "WashTemperature.Warm",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Warm",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Tibia",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Tiède",
"locale": "fr-CA"
}
}
]
}
},
{
"value": "WashTemperature.Hot",
"modeResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Hot",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Caliente",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Chaude",
"locale": "fr-CA"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Example with semantics for blinds
The following example shows a Discover.Response message for blinds that support the Alexa.ModeController interface and uses semantics. Use the ModeController interface for blinds that only fully open and fully close. If your blinds can raise and lower to a range of positions, use the RangeController interface instead.
You can use the ModeController interface for your skills that control blinds in the following locales: de-DE, en-AU, en-GB, en-IN, en-US, es-ES, es-MX, es-US, it-IT, ja-JP.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "manufacturer name",
"description": "<Smart Blinds by Manufacturer>",
"friendlyName": "<Blinds>",
"displayCategories": ["INTERIOR_BLIND"],
"additionalAttributes": {
"manufacturer" : "manufacturer name",
"model" : "sample model",
"serialNumber": "the serial number of the blinds",
"customIdentifier": "your custom identifier for the blinds"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"instance": "Blinds.Position",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.Opening"
}
}
]
},
"configuration": {
"ordered": false,
"supportedModes": [
{
"value": "Position.Up",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Open"
}
}
]
}
},
{
"value": "Position.Down",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Close"
}
}
]
}
}
]
},
"semantics": {
"actionMappings": [
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
"directive": {
"name": "SetMode",
"payload": {
"mode": "Position.Down"
}
}
},
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Open", "Alexa.Actions.Raise"],
"directive": {
"name": "SetMode",
"payload": {
"mode": "Position.Up"
}
}
}
],
"stateMappings": [
{
"@type": "StatesToValue",
"states": ["Alexa.States.Closed"],
"value": "Position.Down"
},
{
"@type": "StatesToValue",
"states": ["Alexa.States.Open"],
"value": "Position.Up"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Example with semantics for a garage door opener
The following example shows a Discover.Response message for a garage door opener that supports the Alexa.ModeController interface and uses semantics. If your device is a garage door opener, you must use both the ModeController interface and the GARAGE_DOOR display category.
For a garage door device, after the user asks to open the garage door, Alexa asks "What is your voice code?" before opening the garage door.
You can use the ModeController interface for your skills that control a garage door in the following locales: en-US.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "manufacturer name",
"description": "Smart Garage Door Opener by Manufacturer",
"friendlyName": "garage door",
"displayCategories": ["GARAGE_DOOR"],
"additionalAttributes": {
"manufacturer" : "manufacturer name",
"model" : "sample model",
"serialNumber": "the serial number of the garage door",
"customIdentifier": "your custom identifier for the garage door"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"instance": "GarageDoor.Position",
"version": "3",
"properties": {
"supported": [
{
"name": "mode"
}
],
"retrievable": true,
"proactivelyReported": true
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.Mode"
}
}
]
},
"configuration": {
"ordered": false,
"supportedModes": [
{
"value": "Position.Up",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Open"
}
},
{
"@type": "text",
"value": {
"text": "Open",
"locale": "en-US"
}
}
]
}
},
{
"value": "Position.Down",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Close"
}
},
{
"@type": "text",
"value": {
"text": "Closed",
"locale": "en-US"
}
}
]
}
}
]
},
"semantics": {
"actionMappings": [
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
"directive": {
"name": "SetMode",
"payload": {
"mode": "Position.Down"
}
}
},
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Open", "Alexa.Actions.Raise"],
"directive": {
"name": "SetMode",
"payload": {
"mode": "Position.Up"
}
}
}
],
"stateMappings": [
{
"@type": "StatesToValue",
"states": ["Alexa.States.Closed"],
"value": "Position.Down"
},
{
"@type": "StatesToValue",
"states": ["Alexa.States.Open"],
"value": "Position.Up"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
SetMode directive
Support the SetMode directive so that users can set the mode of a device.
The following example shows a user utterance:
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
SetMode directive payload details
| Field | Description | Type |
|---|---|---|
mode |
The mode to set for the device. | String |
SetMode directive example
The following example illustrates a SetMode directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "SetMode",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"mode": "WashCycle.Normal"
}
}
}
SetMode response event
If you handle a SetMode directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
In the context object, include the values of all properties that changed. You must include the instance for each mode property that you're reporting.
SetMode response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"value": "WashCycle.Normal",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SetMode directive error handling
If you can't handle a SetMode directive successfully, respond with an Alexa.ErrorResponse event. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.
AdjustMode directive
For modes that have an order, support the AdjustMode directive so that users can adjust the mode of a device.
When you set configuration.ordered to true in the discovery response, with this directive, users can increase or decrease the mode by a specified delta. This directive doesn't restrict requests based on the current mode. That means you can support wrapped modes by appropriately handling requests to increase and decrease the mode.
The following example shows a user utterance:
Alexa, increase the water temperature on the washer.
AdjustMode directive payload details
| Field | Description | Type |
|---|---|---|
modeDelta |
The amount by which to change the mode. The default is 1. | Integer |
AdjustMode directive example
The following example illustrates an AdjustMode directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "AdjustMode",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"modeDelta": 1
}
}
}
AdjustMode response event
If you handle an AdjustMode directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
In the context object, include the values of all properties that changed. You must include the instance for each mode property that you're reporting.
AdjustMode response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"value": "WashTemperature.Warm",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
AdjustMode directive error handling
If you can't handle an AdjustMode directive successfully, respond with an Alexa.ErrorResponse event. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.
State reporting
Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. For details about state reports, see Understand State and Change Reporting.
The response contains the current state of all the retrievable properties in the context object. You must include the instance for each mode property that you're reporting. You identify your retrievable properties, and your instance names, in your discovery response.
When a mode isn't set, for example, when the device is off, report null for the mode property.
Support the ReportState directive so that users can ask about the features of their devices.
The following examples show some user utterances:
Alexa, what is the current washer cycle?
StateReport response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"value": "WashCycle.Delicates",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
You send a ChangeReport event to proactively report changes in the state of an endpoint. For details about change reports, see Understand State and Change Reporting.
The ChangeReport contains the value of all properties that changed in the payload object. You must include the instance for each mode property that you're reporting. You identify the properties that you proactively report, and your instance names, in your discovery response.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"value": "WashTemperature.Hot",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {}
}