Works with Alexa Skill Requirements
If your product connects to Alexa through an Alexa skill, your skill must meet the following requirements to obtain Works with Alexa (WWA) certification. Before you submit your product for WWA certification, your skill must receive skill certification.
For details about smart home skills, see Understand Smart Home Skills.
Mobile app requirements
If your device has a mobile app for setup, you must implement account linking from your app to the Alexa app. Your app must support both iOS and Android. For details, see App-to-App Account Linking.
General skill requirements
Your smart home skill must use the smart home model and include code in an AWS Lambda function to provide communication between Alexa and your product. For details, see Steps to Build a Smart Home Skill.
In addition, your smart home skill must meet the following requirements:
- 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. For details, see Alexa.Discovery.
- You must include
modelin the additionalAttributes object in the discovery response. For Alexa to identify unique devices, include as many other attributes as you can.
- Implement the required capability interfaces for the features your product supports. Return all supported capabilities in the discovery response. For details about the required capabilities, see Device requirements.
- Follow the state and change reporting requirements.
- To let Alexa know the health of your device, implement EndpointHealth. As a best practice, support as many
EndpointHealthproperties as you can.
- Support account linking. For details, see Understand Account Linking.
- Support proactive management. For details, see How to Proactively Manage Endpoints.
- If your skill connects Alexa to Matter-enabled devices, follow the Skill requirements for Matter-enabled products.
- Receive skill certification and publish in the Alexa skill store. For details, see Smart Home and Video Skill Certification Guide.
State and change reporting requirements
Reporting the state of your product enables Alexa to accurately reflect the status of smart home devices in the Alexa app. For details about state and change reporting, see Understand State and Change Reporting and Send Events to the Event Gateway.
Your skill must implement state and change reporting as follows:
- Mark all capability properties as
proactivelyReportedin your discovery response. For details, see Alexa.Discovery.
- Always report the state of all capability properties in the context of an
Alexa.Responseevent when you respond to a control directive, including properties defined by
EndpointHealth. For details, see Report state in an Alexa.Response.
- Respond to
StateReportevents. For details, see Report State in a StateReport.
- Proactively report the state of your device to Alexa by sending
ChangeReportevents when the device state changes for any reason. For details, see Report State in a ChangeReport.
- When the state of a reported property changes, you must send a
ChangeReportwith the new property value within three seconds of the state change. The
ChangeReportmust also include the current value of the
connectivityproperty, defined by the Alexa.EndpointHealth interface.
- If the
connectivityof the device changes to
OK, send the report in three seconds or less.
- If a
ChangeReportevent fails with HTTP errors 503, 429, or 401, or the message times out, try to resend the
ChangeReport. When you resend, do so at least two more times with a delay of no more than 15-second intervals between each try. For details, see event responses.
Skill requirements for Matter-enabled products
If your skill connects Matter-enabled devices to Alexa, these devices might connect to Alexa over multiple routes. For example, a customer might have more than one Alexa smart home skill linked to their Alexa account to control the same device, and that account can have a local Matter connection to the same device. Your skill must provide device identification information so that Alexa can represent these skill-reported and Matter-reported endpoints to the customer as a single device, and not three different devices. Here, a Matter-reported endpoint can be a native Matter device that connects directly to the Matter fabric or a non-Matter device exposed as a bridged device through a Matter Bridge.
If your skill connects Matter-enabled devices to Alexa, either directly or by a Matter Bridge, you must report the following Matter attributes to Alexa in the
AddOrUpdateReport events from your skill:
- Populate the
endpoint.additionalAttributes.customIdentifierproperty with the value of the
UniqueIDattribute of the Basic Cluster for native Matter devices or the Bridged Basic Cluster for Matter Bridged devices.
- In the
endpoint.connectionsarray, report the connection type as
MATTERand include the
ProductIDattributes for the Matter device. If known, include the
Also, Amazon recommends that you report the
macNetworkInterface, if available.Important: If the MAC address changes, you must report the updated
macAddressto Alexa proactively by sending an
AddOrUpdateReportevent to the Alexa event gateway.
- In the
endpoint.friendlyNameproperty, make sure that the name that your skill reports matches the
NodeLabelattribute of the Basic Cluster for native Matter devices or the Bridged Basic Cluster for Matter Bridged devices, unless the attribute isn't set. When populated, if the customer changes the friendly name on your app, make sure that you update the
NodeLabelfield to reflect the change. After you update the
NodeLabel, send an
AddOrUpdateReportevent with the updated
endpoint.friendlyNameto the Alexa event gateway proactively.
Your skill-connected Matter device or Matter Bridge can connect locally with Matter to Alexa-enabled devices, including most Echo models. This option enables Alexa to control these devices locally, which can reduce latency and overall load on your skill. To enable Alexa to establish a local connection with your Matter devices or Matter Bridge, implement Alexa.Commissionable in your skill.
In addition, any Matter-enabled products that your company makes must meet the Matter requirements for WWA certification.
Register your skill with Amazon
If your skill reports a Matter device to Alexa, contact Amazon to register your skill.
To contact the Amazon Matter team
- Sign in to the Alexa developer console.
- Open the Alexa Developer Contact Us page.
- Under Type, choose Skill Building.
- Under Category, choose Smart Home.
- In the Subject and Description boxes, provide your skill ID, Matter
- To send the question, click Submit.
Enable your skill for testing in the Alexa developer portal and test it thoroughly with your device, an Alexa-enabled device, and the Alexa app. Your skill must respond quickly and handle error conditions correctly to pass the WWA certification process. For details, see Debug Your Smart Home Skill. To test and debug device state in the developer console, see View Device State.
Recommended performance targets
To provide the best smart home experience for the customer, Amazon recommends that your Alexa skill meets and maintains the following operational performance targets:
- Latency – After Alexa sends a request to your skill, Alexa must receive a response within 1000 milliseconds 90 percent of the time (P90), and within 800 milliseconds 50 percent of the time (P50).
- Accuracy rate – The response to a
ReportStatedirective must match the
ChangeReportevent that you last sent to Alexa at least 97 percent of the time.
Last updated: Apr 25, 2023