Alexa.PowerController Interface 3

Implement the Alexa.PowerController interface in your Alexa skill so that users can turn their smart home devices on and off. For more details about Smart Home skills, see Understand Smart Home Skills.

For the list of languages that the PowerController 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

When you use the Alexa.PowerController interface, the voice interaction model is already built for you. After the user says one of the following utterances, Alexa sends a corresponding directive to your skill.

The following examples show some user utterances:

Alexa, turn on the vacuum.
Alexa, turn off the lights.

Alexa, Staubsauger einschalten.
Alexa, schalte das Licht aus.

Alexa, allume l’aspirateur.
Alexa, éteins les lumières.

Alexa, वैक्यूम चालू करें।
Alexa, लाइट बंद कर दो।

Alexa, accendi l'aspirapolvere.
Alexa, spegni le luci.

アレクサ、＜device name＞をつけて
アレクサ、＜device name＞を消して

Alexa, ligue o aspirador.
Alexa, apague as luzes.
Alexa, desligue as luzes.

Alexa, enciende la aspiradora.
Alexa, apaga las luces.

Alexa, zet de stofzuiger aan.
Alexa, zet de lampen uit.

Reportable properties

The Alexa.PowerController interface uses the powerState property as the primary property. The valid values are ON or OFF.

Discovery

You describe endpoints that support Alexa.PowerController using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for all interfaces and properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for interfaces and properties that you proactively report to Alexa in a change report.

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

For directives that require user verification before Alexa performs the action, include the verificationsRequired object in your discovery response. For more details, see Directives that require user verification.

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.

Discover response example

The following example shows a Discover.Response message for an Alexa skill that controls a light and supports the Alexa.PowerController and Alexa.BrightnessController interfaces.

Copied to clipboard.

{
  "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 of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Living Room Light",
          "displayCategories": ["LIGHT"],
          "additionalAttributes":  {
            "manufacturer": "Manufacturer of the endpoint",
            "model" : "Model of the device",
            "serialNumber": "Serial number of the device",
            "firmwareVersion" : "Firmware version of the device",
            "softwareVersion": "Software version of the device",
            "customIdentifier": "Optional custom identifier for the device"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.BrightnessController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "brightness"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "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.PowerController interface directives to your skill.

TurnOn directive

Support the TurnOn directive so that users can turn on devices.

The following example shows a user utterance:

Alexa, turn on the vacuum.

Alexa, Staubsauger einschalten.

Alexa, allume l’aspirateur.

Alexa, वैक्यूम चालू करें।

Alexa, accendi l'aspirapolvere.

アレクサ、掃除機をオンにして
アレクサ、＜device name＞をつけて

Alexa, ligue o aspirador.

Alexa, enciende la aspiradora.

Alexa, zet de stofzuiger aan.

TurnOn directive example

The following example illustrates a TurnOn directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "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": {}
  }
}

TurnOn directive payload

The TurnOn directive doesn't define any payload parameters. Include an empty payload object.

TurnOn response

If you handle a TurnOn directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.

The following example shows a TurnOn 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.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOn directive error handling

If you can't handle a TurnOn directive successfully, respond with an Alexa.ErrorResponse event.

TurnOff directive

Support the TurnOff directive so that users can turn off devices.

The following example shows a user utterance:

Alexa, turn off the lights.

Alexa, schalte das Licht aus.

Alexa, éteins les lumières.
Alexa, éteindre les lumières s'il te plaît.

Alexa, लाइट बंद कर दो।

Alexa, spegni le luci.

アレクサ、電気を消して
アレクサ、＜device name＞をオフにして

Alexa, apague as luzes.
Alexa, desligue as luzes.

Alexa, apaga las luces.

Alexa, zet de lampen uit.

TurnOff directive example

The following example illustrates a TurnOff directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOff",
      "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": {}
  }
}

TurnOff directive payload

The TurnOff directive doesn't define a payload. Include an empty payload object.

TurnOff response

If you handle a TurnOff directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.

The following example shows a TurnOff 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.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOff directive error handling

If you can't handle a TurnOff directive successfully, respond with an Alexa.ErrorResponse event.

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. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

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.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

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.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2024-05-01T09:32:05.05Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-05-01T09:31:00.00Z",
    "uncertaintyInMilliseconds": 0
  }
}

Require user verification

When a user attempts to turn on or turn off a device, you can optionally require the user to verify the action before Alexa performs it. To require user verification, specify which directives you require verification for in your Discover.Response. For details, see verificationsRequired object and example for a thermostat that requires user verification.

The following example shows a sample conversation when you require user verification:

Alexa, turn on the living room air conditioner.
The living room air conditioner will be turned on. Do you want to continue?
Yes.
The living room air conditioner is turned on.

アレクサ、リビングのエアコンをつけて。
リビングのエアコンをつけるんですね？
はい。
リビングのエアコンをつけました。

Works with Alexa guidelines

Works with Alexa (WWA) is a certification program that establishes your product's compatibility with Alexa. This certification makes sure that your customers have a better smart home experience. For details about the WWA program, see Works with Alexa Overview.

For devices that implement Alexa.PowerController, verify that your product meets the following requirements before you apply for WWA certification:

  • Your device must respond to user requests in less than two seconds. A response that takes longer than five seconds is considered a latency failure.
  • All properties must be retrievable in state reports and proactivelyReported in change reports.
  • Run the WWA PowerController tests. You can find these test plans on the Alexa Certification Console under Resources > Test Plans.
Was this page helpful?

Last updated: Aug 23, 2024