Your Alexa Consoles
Sign In
Sign In

Alexa.ModeController Interface

The ModeController interface enables your skill to model components of an endpoint that can be set to one of a list of values. The list can be ordered, but that's not required. Use ModeController to model components of a device that have more than one setting. You can include multiple instances of a ModeController on a single endpoint, as long as they have unique values in the instance and friendlyNames fields.

ModeController is highly configurable and enables you to model many different kinds of settings for many different kinds of devices. For some devices, the following interfaces might be a better fit:

Use one of these more specific interfaces if it's appropriate for your device.

Discovery response

All smart home skills must send a discovery response (Discover.Response) that describes the devices associated with the customer's account.

Example discovery response

The following example shows a discovery response for a smart home skill that implements the ModeController interface.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Washer-001",
          "friendlyName": "Washer",
          "description": "Smart Washer by Washer Maker Plus",
          "manufacturerName": "Washer Maker Plus",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ModeController",
              "version": "3",
              "instance": "Washer.WashCycle",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Wash Cycle",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Wash Setting",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "mode"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "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",
              "version": "3",
              "instance": "Washer.WashTemperature",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Wash Temperature",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.WaterTemperature"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "mode"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "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"
            }
          ]
        }
      ]
    }
  }
}

Discovery response fields

The following table describes the fields that are specific to the discovery response for devices that implement the ModeController interface. All fields are required.

Field Description Type
instance A unique identifier for this instance of the ModeController interface. string that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ &
capabilityResources A capabilityResources object specifying the names that customers can use for VUI and GUI interactions. object
supportedModes An array of Mode objects that specify the modes supported by this instance of the ModeController array of Mode objects
ordered Specifies whether the modes have an order. Only ordered modes support the adjustMode directive. Ordered mode values should be configured in increasing order. Boolean

Mode object

The following table describes the fields in a Mode object. All fields are required.

Field Description Type
value Specifies a unique identifier for each possible mode value. string
modeResources An object that contains all localizable resources for the mode. ModeResources object

ModeResources and capabilityResources objects

For more information on ModeResources and capabilityResources objects, see Resources and Assets.

Directives

The ModeController interface supports directives to set and adjust the mode, and to query the current mode. The following example is a query utterance:

User: Alexa, what is the wash setting on the washer?

SetMode

Customers can request to set the mode. For example:

User: Alexa, set the wash cycle to cottons.
User: Alexa, set the wash setting on the washer to normal.

The following example shows a SetMode directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ModeController",
      "name": "SetMode",
      "instance": "Washer.WashCycle",
      "messageId": "a3c0e1e3-c924-469d-bb46-78d3fd3f2bfe",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "Washer-001",
      "cookie": {}
    },
    "payload": {
      "mode": "WashCycle.Normal"
    }
  }
}

Payload fields

The following table describes the fields in the payload of a SetMode directive.

Field Description Type
mode The mode value to set for the component. string

AdjustMode

For modes that are ordered, customers can increase or decrease the mode by the specified delta. The default delta is 1. 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.

For example:

User: Alexa, increase the water temperature on the washer.

The following example shows an AdjustMode directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ModeController",
      "name": "AdjustMode",
      "instance": "Washer.WashTemperature",
      "messageId": "c5c5bb3b-039b-4a29-bc1c-e74abf69a981",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<the identifier of the target endpoint>",
      "cookie": {}
    },
    "payload": {
      "modeDelta": 1
    }
  }
}

Payload fields

The following table describes the fields in the payload of an AdjustMode directive.

Field Description Type
modeDelta Indicates the value of the adjustment. Can be a positive or negative. number

Properties and events

When the state of a mode value changes, send a state report with a mode property. You must also include the instance to specify which ModeController of the endpoint you are reporting state for.

When a mode value is not currently set (for example, the device is off), report a mode value of null.

Property name Description Type
mode The current value of the ModeController. string

For example:

{
    "name": "mode",
    "value": "WashCycle.Normal"
}

ErrorResponse

You should respond with an error when you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more information.