Works with Alexa Skill Requirements
A skill for any device that receives the Works with Alexa (WWA) badge must meet more stringent requirements than the general smart home skill certification requirements.
- Get started
- Alexa skill requirements
- Implement state reporting
- State reporting requirements
- Test state reporting
- Submit your skill for certification
- More information
Log in to developer.amazon.com to start creating an Alexa skill. We recommend using the smart home model. Your skill includes code in a Lambda function, which provides the communication between Alexa and your products. For more information about creating a skill with the smart home model, see Understand the Smart Home Skill API. WWA-specific requirements are outlined in the next sections.
Alexa skill requirements
For your product to be eligible for Works with Alexa certification, your skill must:
- Target version 3 of the Smart Home API. In device discovery, describe the payload version as 3, and specify each capability listed as version 3. See Alexa.Discovery for more information.
- Return all supported capabilities for all models in the discovery response. Your skill might support a combination of Smart Home APIs with custom intents. See Alexa.Discovery for Smart Home APIs and Alexa.CustomIntent (public preview) for custom intents.
- Support account linking. See Understand Account Linking for more information.
- Support proactive management. See How to Proactively Manage Endpoints for more information.
- Implement EndpointHealth. See state reporting requirements 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 Understand State Reporting and Send Events to the Event Gateway.
State reporting requirements
To be WWA compliant, the skill that accompanies a device must do the following:
- Mark capability properties as
proactivelyReportedin 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.
- When the state of a reported property changes, you must send a ChangeReport with the new property value within three 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 to
OK, send the report in three seconds or less.
- If the
ChangeReportevent fails with HTTP errors 503, 429, or 401, or the message times out, try to resend the
ChangeReportat least two more times with a delay of no more than 15 second intervals between each try. For more information, see the error section of the Send Events to the Alexa Event Gateway.
Following is the list of capabilities these requirements apply to:
- Alexa.ModeController (preview)
- Alexa.RangeController (preview)
- Alexa.ToggleController (preview)
Test state reporting
Enable your skill for testing in the development portal and test it thoroughly with your product using an Alexa-enabled device or app. Your product must respond quickly and handle error conditions correctly to make it through the certification process. For more information, see Debug Your Smart Home Skill.
Submit your skill for certification
Your skill must be published in the Alexa Skills store for your Works with Alexa certification to be complete. To publish your skill, it must pass skill certification. Submit the skill for certification using the developer console or ASK CLI. Works with Alexa certification is a separate process.
For general guidelines about the Works with Alexa program, and how to submit your devices for testing, see Certify Your Device with Works with Alexa.