Works with Amazon Alexa Requirements for a Smart Home Skill
A skill for any device that receives the WWAA badge must meet more stringent requirements than the general smart home skill certification requirements.
- Get started
- Target version 3
- Implement state reporting
- Report device health
- Ensure your skill meets performance requirements
- Thoroughly test your products and skill with Alexa
- Submit your skill for certification
- More information
Log in to developer.amazon.com to start creating a smart home skill. A smart home skill includes code in a Lambda function, which provides the communication between Alexa and your products. Learn more about creating a smart home skill. WWAA-specific requirements are outlined in the next sections.
Target version 3
You must target Smart Home Skill API version 3, which means your skill:
- Implements v3 capabilities.
- In device discovery, describes the
3, and each capability listed specifies the
3. See Alexa.Discovery for more information.
Implement state reporting
State reporting enables the Alexa app to accurately reflect the status of smart home devices. You should review general information about state reporting as a prerequisite to this section. See State Reporting in a Smart Home Skill and Send Events to the Alexa Event Gateway.
To be WWAA compliant, the smart home skill that accompanies a device must do the following:
- Mark capability properties as
proactivelyReportablein your discovery response.
- Always report the state of all capability properties in the context of an Alexa.Response event when you respond to a control directive, including properties defined by
- Respond to ReportState directives with StateReport events.
- Send ChangeReport events when the device state changes for any reason.
Following is the list of capabilities these requirements apply to:
- Alexa. BrightnessController
Report device health
Your skill must implement the Alexa.EndpointHealth interface if any capability implemented by the skill reports property state.
Ensure your skill meets performance requirements
To meet WWAA badge requirements, you must report property state changes in a timely manner:
- When the state of a reportable property changes, you must send a
ChangeReportwith the new property value within 3 seconds of the state change. The
ChangeReportmust also include the current value of the
connectivityproperty, which is defined by the Alexa.EndpointHealth interface.
If the connectivity of the device changes, then the following rules apply:
- If the state of
OK, send the report in 3 seconds or less
- If the state of
UNREACHABLE, report within the following guidelines:
Device category Reporting guideline Notes Bulbs < 1 minute Poll frequently as the device can be toggled off with a switch Hubs < 1 minute Unlikely to go offline Plugs < 1 minute Unlikely to go offline Thermostats and heating and cooling devices < 1 minute Unlikely to go offline Switches < 24 hour Very unlikely to go offline as these devices are typically hardwired Locks < 12 hour Typically battery powered.
- If the state of
Additional state reporting requirements:
- If the
ChangeReportevent fails with error 503, 429, 401 or the message times out, try to resend the
ChangeReportat least 2 more times with a delay of no more than 15 second intervals between each try.
Thoroughly test your products and skill with Alexa
Enable your skill for testing in the development portal and test it thoroughly with your product using an Alexa-enabled device or app. You product must respond quickly and handle error conditions correctly to make it through the certification process.
Submit your skill for certification
When you submit your skill for certification, you must identify that you’d like to be considered for the Works with Amazon Alexa program, include a “#WorksWithAmazonAlexa” identifier in the Testing Instructions section of the developer portal prior to skill submission. Provide this identifier in addition to other information such as descriptions and images that are required in the Amazon Developer Portal.
For general guidelines about the WWAA program, and how to submit your devices for testing, see Obtain the Works with Amazon Alexa Badge for Your Devices.