Works with Alexa Add-on Requirements

---

If your product connects to Alexa through a smart home add-on, your add-on must meet the following requirements to obtain Works with Alexa (WWA) certification. Before you submit your product for WWA certification, your add-on must receive skill certification.

For details about smart home add-ons, see Connect Your Device Cloud with Smart Home Add-ons.

Mobile app requirements

If your device has a mobile app for setup, you must implement both versions of app-to-app account linking, starting your app and starting from the Alexa app. Your app must support both iOS and Android and be available in the iOS and Android app stores. For more details, see App-Initiated App-to-App Account Linking and Alexa-Initiated App-to-App Account Linking.

In addition, your app and add-on must stay synchronized and meet the following requirements:

• The endpoint.friendlyName reported by your add-on should match the device name shown in your app.
• When a customer renames a device in your app, send an AddOrUpdateReport event from your add-on and include the updated endpoint.friendlyName property.
• When a customer or your service removes a device from your app, send a DeleteReport event from your add-on to remove the endpoint from Alexa.

General add-on requirements

Your smart home add-on 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 Smart Home Add-ons.

In addition, your smart home add-on 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 manufacturer and model in 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 EndpointHealth properties as you can.
• Support account linking. You must implement both versions of app-to-app account linking: starting from your app and starting from the Alexa app.
• Support proactive management. For details, see How to Proactively Manage Endpoints.
• If your device has a mobile app, your add-on must also meet the synchronization requirements in Mobile app requirements.
• If your add-on connects Alexa to Matter-enabled devices, follow the Add-on requirements for Matter-enabled products.
• Receive skill certification and publish in the Alexa Skills Store. For details, see Smart Home and Video 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 and on Alexa-enabled devices with a screen. For example, the tiles on the Amazon Echo Hub show customers a quick view about the status of their Alexa-connected smart devices. In addition, Alexa uses the current state in Alexa Routines and in response to customer requests for the status of their smart device. The visibility of device state makes reliable and accurate state reporting essential to the user experience.

Your add-on must implement state and change reporting as follows:

• Mark all reportable capability properties as retrievable = true and proactivelyReported = true in your discovery response for each of the interfaces that your add-on supports. For details, see Alexa.Discovery.
• 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 Alexa.EndpointHealth. For details, see Report state in an Alexa.Response.
• Respond to ReportState directives with StateReport events. For details, see Report State in a StateReport.
• When you respond to a ReportState directive for an endpoint that's currently unreachable, return StateReport with the value of the connectivity property set to UNREACHABLE for the Alexa.EndpointHealth interface.
• Proactively report the state of your device to Alexa by sending ChangeReport events when the state of any reportable property changes for any reason, including a state change that happens because of a directive from Alexa. For details, see Report State in a ChangeReport.
• 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 ChangeReport must also include the current value of the connectivity property, defined by the Alexa.EndpointHealth interface.
• If the connectivity of the device changes from OK to UNREACHABLE or from UNREACHABLE to OK, send the ChangeReport with the updated value of the connectivity property for Alexa.EndpointHealth in three seconds or less.
• If a ChangeReport event 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.

For more details about state and change reporting, see Understand State and Change Reporting and Send Events to the Event Gateway.

Add-on requirements for Matter-enabled products

If your add-on 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 add-on linked to their Alexa account to control the same device, and that account can have a local Matter connection to the same device. Your add-on must provide device identification information so that Alexa can represent these add-on-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 add-on connects Matter-enabled devices to Alexa, either directly or by a Matter Bridge, you must report the following Matter attributes to Alexa in the Discover.Response and AddOrUpdateReport events from your add-on:

• Populate the endpoint.additionalAttributes.customIdentifier property with the value of the UniqueID attribute of the Basic Cluster for native Matter devices or the Bridged Basic Cluster for Matter Bridged devices.
• In the endpoint.connections array, report the connection type as MATTER and include the VendorID and ProductID attributes for the Matter device. If known, include the Discriminator attribute.
  Also, Amazon recommends that you report the macAddress and macNetworkInterface, if available.
  Important: If the MAC address changes, you must report the updated macAddress to Alexa proactively by sending an AddOrUpdateReport event to the Alexa event gateway.
• In the endpoint.friendlyName property, make sure that the name that your add-on reports matches the NodeLabel attribute 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 NodeLabel field to reflect the change. After you update the NodeLabel, send an AddOrUpdateReport event with the updated endpoint.friendlyName to the Alexa event gateway proactively.

Your cloud-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 add-on. To enable Alexa to establish a local connection with your Matter devices or Matter Bridge, implement Alexa.Commissionable in your add-on.

In addition, any Matter-enabled products that your company makes must meet the Matter requirements for WWA certification.

Register your add-on with Amazon

If your add-on reports a Matter device to Alexa, contact Amazon to register your add-on.

To contact the Amazon Matter team

1. Sign in to the Alexa developer console.
2. Open the Alexa Developer Contact Us page.
3. Under Type, choose Skill Building.
4. Under Category, choose Smart Home.
5. In the Subject, enter Matter Dedupe.
6. In the Description, provide the information that you send in the discovery response:
   • Your skill ID
   • Matter Product ID, Vendor ID, and Discriminator
   • MAC address
   • MAC network interface type – BLE, WIFI, ETHERNET, or THREAD
   • Product manufacturer, model, serial number
   • Product software and firmware versions
   • Custom identifier unique ID
7. To send the question, choose Submit.

Testing requirements

Enable your add-on for testing in the Alexa Developer Console and test it thoroughly with your device, an Alexa-enabled device, and the Alexa app. Your add-on must respond quickly and handle error conditions correctly to pass the WWA certification process. For details, see Test and Debug Your Smart Home Add-on. 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 add-on meets and maintains the following operational performance targets:

• Latency – After Alexa sends a request to your add-on, 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 ReportState directive must match the ChangeReport event that you last sent to Alexa at least 97 percent of the time.

When a device loses connectivity, your add-on must detect and report the device as unreachable within the following timeframes.

Device type	Customer interaction target	Passive detection target
Connected to electrical power (mains-powered, always-on)	Within 10 seconds	Within 15 minutes
Battery-powered and intermittent power	Within 20 seconds	Must not exceed 12 hours

Related topics

• Apply for Works with Alexa Certification
• Works with Alexa Security Best Practices

---

---

Last updated: Jul 14, 2026