Alexa.PowerController Interface

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

For the list of languages that the PowerController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.PowerController interface, the voice interaction model is already built for you. The following examples show some user utterances:

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

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

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

アレクサ、<Device name>
アレクサ、<Device name>を消して

After the user says an utterance, Alexa sends a corresponding directive to your skill.

Properties

The powerState property

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 of the 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 the full list of display categories, see display categories.

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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "<a description that is shown in the Alexa app>",
          "friendlyName": "<device name, displayed in the Alexa app>",
          "displayCategories": ["LIGHT"],
          "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",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

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, das Vakuum einschalten.

Alexa, allumer le vide s'il te plaît.

device をつけて

TurnOn directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOn response event

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.

TurnOn response event example

Copied to clipboard.

{
  "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.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, éteindre les lumières s'il te plaît.

device を消して

TurnOff directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOff",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOff response event

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.

TurnOff response event example

Copied to clipboard.

{
  "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.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 of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For more information about state reports, see Understand State Reporting.

StateReport response event example

Copied to clipboard.

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

Change reporting

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

ChangeReport event example

Copied to clipboard.

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

Requiring 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 the 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 raises the bar on responsiveness, reliability, and functionality, ensuring your users have the best smart home experiences. When your products are certified, they can carry the Works with Alexa badge in the Amazon Smart Home Store and on product packaging. For more information, see Certify Your Device with Works with Alexa.

For devices that implement Alexa.PowerController, you should verify the following before applying 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.
  • You must run all the test cases available on GitHub at WWA PowerController tests.