Alexa.ModeController Interface 3

Implement the Alexa.ModeController interface in your Alexa skill so that users can control the mode settings of a device. You can use the Alexa.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 Alexa.ModeController interface is a generic controller interface.

The Alexa.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 languages that the Alexa.ModeController interface supports, see List of Alexa Interfaces and Supported Languages.

For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.ModeController interface uses the pre-built voice interaction model. 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 das Küchenrollo hoch.
Alexa, fahr das Wohnzimmer-Rollo runter.
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

Mode property

The Alexa.ModeController interface uses the mode property as the primary property. The property values are strings. The Mode object defines the acceptable values for the mode.

An endpoint can support multiple modes. To distinguish modes, you must always include the instance attribute. This attribute defines the name of the mode. You identify your instance names in your discovery response.

Mode property example

Copied to clipboard.

{
    "namespace": "Alexa.ModeController",
    "name": "mode",
    "instance": "Washer.WashTemperature",
    "value": "WashTemperature.Cold"
}

Mode object

The Mode object represents an acceptable value for a mode. You include at least two Mode objects in the supportedModes array in your discovery response.

The following example shows two Mode objects in a supportedModes array.

Copied to clipboard.

"supportedModes": [
  {
    "value": "WashCycle.Normal",
    "modeResources": {
    }
  },
  {
    "value": "WashCycle.Delicates",
    "modeResources": {
    }
  }
]

The following table shows the properties of the Mode object.

Field Description Type
value Name of the mode value. String
modeResources Friendly names that users can use to interact with the mode value. ModeResources object

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.

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

Copied to clipboard.

"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 Alexa.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 Alexa.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.

Use semantics to enable announcements

You can use semantics to enable announcements to the user when your device requires attention. Announcements take the form, Your <device friendly name> is <state>. For example, when their automatic vacuum cleaner gets stuck, Alexa notifies the user with the following announcement: "Your vacuum is stuck."

To enable announcements, implement the Alexa.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.Stuck. You trigger announcements by sending an Alexa.ChangeReport to report a change in the device state. For more details about announcement text, see Alexa.ProactiveNotificationSource.

Discovery

You describe endpoints that support Alexa.ModeController by 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.

For connected vehicles that use Alexa user identification, include directiveConfigurations in your discovery response to configure the authentication confidence level and policy name. For details, see directiveConfigurations.

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

Capabilities array

In addition to the usual discovery response fields, for each Alexa.ModeController entry in the capabilities array, include the following fields.

Field Description Type
instance 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. 		CapabilityResources object
configuration.ordered Set to true, if the mode values have an order; otherwise, set to 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.		 Array of Mode objects

Discovery response examples

Washing machine example

The following example shows a Discover.Response message for a washing machine that supports three modes defined by three instances: Washer.WashCycle, Washer.CurrentWashCycle, and Washer.WashTemperature.

Semantics for blinds example

The following example shows a Discover.Response message for blinds that support the Alexa.ModeController interface and uses semantics. Use the Alexa.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 Alexa.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.

Semantics for a garage door opener example

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 Alexa.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 Alexa.ModeController interface for your skills that control a garage door in the following locales: de-DE, en-GB, en-US, es-ES, fr-FR, it-IT.

Directives

Alexa sends the following Alexa.ModeController interface directives to your skill.

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 example

The following example shows a SetMode directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ModeController",
      "instance": "Washer.WashCycle",
      "name": "SetMode",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "mode": "WashCycle.Normal"
    }
  }
}

SetMode directive payload

Property Description Type Required

mode

Mode to set for the device.

String

Yes

SetMode response

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

The following example reports that the Washer.WashCycle mode value changed.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 example

The following example shows an AdjustMode directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ModeController",
      "instance": "Washer.WashTemperature",
      "name": "AdjustMode",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "modeDelta": 1
    }
  }
}

AdjustMode directive payload

Property Description Type Required

modeDelta

The amount by which to change the mode. The default is 1.

Integer

No

AdjustMode response

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.

The following example shows an AdjustMode response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 report. You identify the retrievable properties and 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's the current washer cycle?

アレクサ、洗濯機のモードは何にセットされている？

StateReport response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 report changes proactively 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 report. You identify the properties that you proactively report and the instance names in your discovery response.

ChangeReport event example

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50Z",
    "uncertaintyInMilliseconds": 0
  }
}