Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Get started
Connect with Matter
Alexa Connect Kit
Add-ons
Certify
Resources
Skip to main content
You can build smart home add-ons to connect your devices to Alexa through your cloud infrastructure. With a smart home add-on, customers can voice-control their devices and view device status in the Alexa app and on Alexa-enabled devices with a screen. When a customer speaks to Alexa, Alexa interprets the utterance and sends a message to your add-on that communicates the request. Your add-on reacts by communicating with your device cloud to change the state of the device, such as dimming a light. Alexa can also request information about device state, such as the color of the light, to display in the Alexa app. If you want to connect your smart home device to Alexa locally, see Connect Your Device to Alexa with Matter. If your device supports Matter, Alexa can control the device locally over Matter, and your add-on can handle the cloud connection. For details, see Add-on requirements for Matter-enabled products. If you don’t have existing cloud infrastructure or prefer not to manage Lambda functions, account linking, and cloud services, consider Alexa Connect Kit (ACK). With ACK, Amazon manages the cloud infrastructure, security, and certification, and you focus on your device firmware. For details, see Alexa Connect Kit.

Who can develop smart home add-ons for Alexa?

Anyone with cloud-connected devices can develop a smart home add-on. The Smart Home API uses the pre-built voice interaction model, which defines the utterances that customers say to interact with your add-on. Each interface defines a set of pre-built utterances to control the device. Alexa knows how to interpret the customer’s speech and what directives to send to your add-on. Smart home add-on development falls into two categories:
  • Device manufacturers who want to enable customers to interact with their cloud-connected devices by using voice, the Alexa app, and Alexa-enabled devices with a screen
  • Independent developers who want to create an Alexa add-on for cloud-connected devices, either for their own private use or general public use
You can build your own smart home add-on or work with experienced solution providers to help you connect your devices to Alexa. For a list of solution providers, see Works with Alexa IoT Solution Providers. If you’re a device manufacturer looking for a managed connectivity solution that adds Alexa and Matter support to your device, consider ACK.

What kinds of devices does the Smart Home API support?

You can connect almost any type of device to Alexa by using the Smart Home API. You decide how you want the customer to interact with your device, and then you implement the capability interfaces that support those interactions. For example, your device might be a lamp that customers want to turn on and off. To support this functionality, you implement the Alexa.PowerController interface in your add-on. Most devices implement multiple smart home interfaces to support multiple device features, such as dimming the light and turning the light off and on. For the full list of smart home interfaces, see List of Alexa Interfaces and Supported Languages. Some Alexa interfaces support specific device types, but other interfaces support many kinds of devices. For example, implement the Alexa.ThermostatController interface only for thermostats, but implement interfaces like Alexa.PowerLevelController for many kinds of devices.

How your cloud connects to Alexa

Your smart home add-on uses the smart home model. The add-on code runs in an Amazon Web Services (AWS) Lambda function and handles communication between Alexa and your device. When a customer enables your add-on, Alexa starts device discovery. During discovery, your add-on describes your device and the properties and interfaces that it supports, and reports the device details to Alexa. Then, when a customer asks Alexa to control the device, Alexa sends your add-on a directive. Your add-on reacts to the message by changing the state of the device through your cloud infrastructure. Your add-on uses account linking to connect the customer’s account in your system with their Amazon account. Account linking lets your add-on identify the customer and their devices, and it requires an OAuth 2.0 authorization server. For details, see Account Linking for Smart Home and Other Domains.

Capability interfaces

The Smart Home API provides capability interfaces that you use to describe your devices and the properties, events, and directives that they support. After you receive a Discover directive from Alexa, send a Discover.Response event to describe your device. For details, see About Alexa Discovery. Alexa uses this description of your device and its capabilities to automatically enable certain functionality, such as:
  • Contextual targeting, which uses clues, such as device groups, to target the device when the customer doesn’t name the device explicitly
  • Controlling devices through Alexa Routines
  • Viewing and controlling devices with the Alexa app and on Alexa-enabled devices with a screen

Device updates

The Smart Home API also supports device updates when the state of a device changes. Customers can ask Alexa about the state of a device and view the up-to-date status in the Alexa app and on Alexa-enabled devices with a screen. For example, a customer can check the temperature of their home or see if a light is on. In addition, your add-on or device can proactively notify Alexa when the customer manually changes the device state, such as turning on the light switch. For details, see Understand State and Change Reporting. To support these customer scenarios, the Smart Home API has the following features:
  • Synchronous and asynchronous messaging – When Alexa sends a directive, your smart home add-on responds either synchronously or asynchronously. You’re free to choose asynchronous or synchronous responses or a combination of the two, whichever works best for your device and cloud architecture.
  • Device state change notifications – When you provide proactive state updates to Alexa, Alexa shows accurate, up-to-date device status in the Alexa app and on Alexa-enabled devices with a screen. Proactive updates enable customers to take action, if needed. For example, if someone manually unlocks the door, you can send this change to Alexa to speak or display to the customer.
  • Querying state – Capability interfaces define properties that Alexa can query. Customers can ask Alexa for the current state of a device or view it in the Alexa app.
The following diagram summarizes how smart home add-ons work with Alexa and your device cloud. Alexa smart home add-ons receive directives from the Alexa service, communicate with your device cloud to control devices, and send events back to Alexa.

Example: Control a kitchen light

A customer enables your smart home add-on and links it to their account in your device cloud. Alexa then discovers the devices associated with that account. Later, the customer says, for example, or makes a change to a device setting in the Alexa app. Alexa uses information from the customer’s utterance or the app to compose a message that identifies the endpoint and the operation to perform. Alexa sends this message, called a directive, to your add-on to control the kitchen light. The directive includes:
  • The directive name and interface, for example, BrightnessController.SetBrightness, and the new setting value
  • The endpoint ID, in this example, the ID for the device that the customer named “kitchen light”
  • Information that authenticates the customer
Your add-on code receives and parses the directive, and validates the authentication information. Your add-on communicates with your device, or device cloud, using communication channels you’ve defined, to set the brightness on the customer’s kitchen light. Your add-on responds to Alexa with a message called an event that indicates whether the operation was successful. You can send the event synchronously from the Lambda function or asynchronously from the device cloud. Alexa uses this event to respond to the customer. For example, Alexa might say, to confirm that your add-on handled the directive. Later, the customer switches off the kitchen light manually. This action causes your device cloud to send a ChangeReport event to Alexa to indicate that the light is now off. Alexa displays the updated status in the Alexa app and on Alexa-enabled devices with a screen.

Works with Alexa guidelines

Works with Alexa (WWA) is a certification program that establishes your product’s compatibility with Alexa and helps your customers have a better smart home experience. When your products receive certification, they can carry the Works with Alexa badge in the Amazon Smart Home Store and on product packaging. For details, see Works with Alexa Overview.

Next steps

To understand the components of a smart home add-on, see Smart Home Add-on Concepts. To choose capability interfaces for your device and start building, see Steps to Build Smart Home Add-ons.
Last modified on November 13, 2026