Alexa.ModeController Interface 3

Implement the Alexa.ModeController interface in your Alexa add-on 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:

Alexa.Cooking and CookingMode
Alexa.EqualizerController and Mode
Alexa.LockController and LockState
Alexa.ThermostatController and ThermostatMode

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. After the user says one of the following utterances, Alexa sends a corresponding directive to your add-on. The following examples show some user utterances:

You can enable additional utterances by using semantics. The following examples show user utterances enabled with semantics:

Properties and objects

The Alexa.ModeController interface defines the following 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

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

"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

"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 , , , and 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 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: To enable announcements, implement the Alexa.ProactiveNotificationSource interface in your Alexa add-on. 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 add-on 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 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. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Capabilities object

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.

Show/hide discovery response

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

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 add-ons 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.

Show/hide discovery response

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

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

Show/hide discovery response

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.ModeController interface directives to your add-on.

SetMode directive

Support the SetMode directive so that users can set the mode of a device. The following examples show user utterances:

SetMode directive example

The following example shows a SetMode directive that Alexa sends to your add-on.

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

{
  "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:00.00Z",
        "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 examples show user utterances:

AdjustMode directive example

The following example shows an AdjustMode directive that Alexa sends to your add-on.

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

{
  "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:00.00Z",
        "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:

StateReport response example

{
  "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:00.00Z",
        "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

{  
  "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": "2024-02-03T17:10:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-02-03T17:08:20.12Z",
    "uncertaintyInMilliseconds": 10000
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Properties and objects

Mode property

Mode property example

Mode object

ModeResources object

Semantics

Use semantics to enable additional utterances

Use semantics to enable announcements

Discovery

Capabilities object

Discovery response examples

Washing machine example

Semantics for blinds example

Semantics for a garage door opener example

Directives

SetMode directive

SetMode directive example

SetMode directive payload

SetMode response

SetMode directive error handling

AdjustMode directive

AdjustMode directive example

AdjustMode directive payload

AdjustMode response

AdjustMode directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Properties and objects

​Mode property

​Mode property example

​Mode object

​ModeResources object

​Semantics

​Use semantics to enable additional utterances

​Use semantics to enable announcements

​Discovery

​Capabilities object

​Discovery response examples

​Washing machine example

​Semantics for blinds example

​Semantics for a garage door opener example

​Directives

​SetMode directive

​SetMode directive example

​SetMode directive payload

​SetMode response

​SetMode directive error handling

​AdjustMode directive

​AdjustMode directive example

​AdjustMode directive payload

​AdjustMode response

​AdjustMode directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Properties and objects

Mode property

Mode property example

Mode object

ModeResources object

Semantics

Use semantics to enable additional utterances

Use semantics to enable announcements

Discovery

Capabilities object

Discovery response examples

Washing machine example

Semantics for blinds example

Semantics for a garage door opener example

Directives

SetMode directive

SetMode directive example

SetMode directive payload

SetMode response

SetMode directive error handling

AdjustMode directive

AdjustMode directive example

AdjustMode directive payload

AdjustMode response

AdjustMode directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics