Alexa.ModeController Interface

The Alexa.ModeController capability interface describes messages used to control the mode settings of an endpoint. You can use the ModeController interface to model properties of an endpoint that can be set to one of a list of values, such as the wash cycle mode of a washing machine. The list of values can be ordered, but that's not required. You can also use the ModeController interface to model properties of an endpoint that users can't change.

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:

For the list of locales that are supported for the ModeController interface, see List of Capability Interfaces and Supported Locales.

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 is 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 optionally enable additional utterances by using semantics. The following examples show some additional user utterances:

Alexa, open the garage door.
Alexa, close the garage door.
Alexa, raise the bedroom blinds.
Alexa, lower the living room blinds.

Alexa, öffne das Garagentor.
Alexa, schließe das Garagentor.
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, so 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

{
  "value": "WashCycle.Normal",
  "modeResources": {
    "friendlyNames": [
      {
        "@type": "text",
        "value": {
          "text": "normal",
          "locale": "en-US"
        }
      },
      {
        "@type": "text",
        "value": {
          "text": "cottons",
          "locale": "en-US"
        }
      }
    ]
  }
}

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 is displayed in the Alexa mobile app. For more information, see Resources and Assets.

ModeResources object example

The following example shows the mode resources for the night mode of a fan. The skill provides two friendly names: Alexa.Setting.Night as an asset, and White Noise as text. Users say phrases like "Alexa, set the fan speed to night mode" or "Alexa, set the fan to white noise."

"modeResources":
{
  "friendlyNames": [
    {
      "@type": "asset",
      "value": {
        "assetId": "Alexa.Setting.Night"
      }
    },
    {
      "@type": "text",
      "value": {
        "text": "white noise",
        "locale": "en-US"
      }
    }
  ]
}

Using 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 more information, 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.

You can support semantics on different controllers for the same device, however each controller must support different phrases. For example, you can support "open" on a ModeController, and "raise" on a RangeController, but you can't support "open" on both ModeController and RangeController.

To use semantics, include a semantics object in your discover response as described in the following section.

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 more information, see using semantics to enable additional utterances.

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. 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. Only modes that are ordered support the AdjustMode directive. Boolean
configuration.
supportedModes		 The values that are accepted for the mode. Ordered mode values should be listed in increasing order. An array of mode objects.

Discover response examples

Example

The following example shows a Discover.Response message for a washing machine endpoint 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"],
          "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": "text",
                    "value": {
                      "text": "wash cycle",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "wash setting",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "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"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": "WashCycle.Delicates",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "delicates",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@type": "text",
                          "value": {
                            "text": "knits",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "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": "text",
                    "value": {
                      "text": "wash temperature",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.WaterTemperature"
                    }
                  }
                ]
              },
              "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"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": "WashTemperature.Warm",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "warm",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": "WashTemperature.Hot",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "hot",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "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"],
          "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.

{
  "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"],
          "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": "text",
                          "value": {
                            "text": "Open",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.Open"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": "Position.Down",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Closed",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@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"
            }
          ]
        }
      ]
    }
  }
}

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

{
  "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 are 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

Support the AdjustMode directive so that users can adjust the mode of a device.

For modes that are ordered, users can increase or decrease the mode by a specified delta. This directive does not 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

{
  "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 are 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 more information about state reports, see Understand State Reporting.

The response contains the current state of all of the retrievable properties in the context object. You must include the instance for each mode property that you are reporting. You identify your retrievable properties, and your instance names, in your discovery response.

When a mode is not 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 more information about change reports, see Understand State 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 are 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": {}
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment