Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Alexa+ Smart Home Docs

Get started

Connect with Matter

Alexa Connect Kit

Add-ons

Certify

Resources

感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Publish a Device with Custom Capabilities

Smart home skills are now called smart home add-ons. No action is needed, and your existing integration will continue to operate normally.

Important: At this time, the Smart Home AI Toolkit is in preview and is not publicly available. To try the feature, contact your Amazon representative for access.

After you build and test your custom capabilities, use the Smart Home AI Toolkit to publish your device. To publish, generate the UI for the Alexa app, and then submit the device for Amazon review.

Prerequisites

Before you publish, confirm the following items:

Every custom capability has a current utterance dataset and a passing batch evaluation.
The full device utterance dataset exists, and the batch evaluation passed.

For details about testing requirements, see Test Custom Capabilities. To review the capabilities included in your device, see View the device.

Generate the UI

In this step, you build an interactive UI prototype that Alexa displays in the Alexa app and on Alexa-enabled devices with a screen when the customer interacts with your device. The AI-generated UI gives customers a tap interface to control the device. To enable you to preview real device values in the generated UI, you can simulate discovery, state report, directive, and error responses.

Tip: Create a UI to improve the customer's experience when they manage the device. Design settings and controls that are intuitive and functional. The Alexa+ smart home agent updates the UI as the conversation progresses.

To generate the Alexa app UI for your device

On the menu, choose UI.
To render the UI, choose Generate UI.
Review the generated UI to make sure it reflects the capabilities of your device, including pre-built and custom capabilities.
To make changes to the UI, chat with the agent to add, update, remove, or move UI elements.
To view the rendered UI on receipt of responses from your add-on, open the following tabs:
- Discovery response – To edit the discovery response, chat with the agent, or update the response directly in the viewer, and then choose Apply.
- State Report – To change property values, chat with the agent, or update the context directly in the viewer, and then choose Apply.
- Directive response – To preview UI changes after the customer asks Alexa to control the device, under Directive, open the drop-down, select the directive, and then choose Confirmation or Error.
To review UI changes, open the UI tab.
If you change the definition of any custom capabilities associated with the device, or if you add or remove pre-built capabilities, to update the UI, choose Regenerate.

Publish the device

To include the custom capabilities in your smart home add-on, you publish the device.

A device is ready to publish after it meets the following criteria:

Every custom capability has a current evaluation that has passed.
A full device utterance dataset exists, and the batch evaluation passed.
A device UI exists.

Note: Amazon has sole discretion to determine whether to review or approve custom capabilities.

To publish a device

On the menu, choose Deploy.
Review the Deployment readiness checklist. If any items aren't complete, resolve them as follows:
- If the utterance dataset for a custom capability isn't up to date, return to Test Custom Capabilities to regenerate the dataset.
- If the utterance evaluation fails for a custom capability, return to Build Custom Capabilities to update the capability definition and rerun the evaluation.
- If the utterance dataset for the device isn't up to date or the batch evaluation failed, regenerate the utterance dataset and run the evaluation.
After the Deployment readiness status is Complete, under Publish device, choose Submit for Publication.

Next steps

After you publish your device with custom capabilities, you can add the interface to the Amazon Web Services (AWS) Lambda function for your add-on. You implement discovery, state handling, and directive processing for your custom interface in the same way you do for pre-built Alexa interfaces. For details, continue with Step 2 in Steps to Build Smart Home Add-ons.

Review the following examples of a custom capability in a smart home add-on.

Important: AI can make mistakes. Review the generated capability definition before you use it in your smart home add-on.

Example discovery response

The following example shows an instance of the custom capability in a discovery response. Use the version of the custom capability that you saved in the Smart Home AI Toolkit.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "AnyCompany",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "AnySmartProduct",
                "displayCategories": ["LIGHTS"],
                "additionalAttributes": {
                    "manufacturer": "AnyCompany",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Custom.AnyCompany.SampleController",
                        "version": "1.0",
                        "properties": {
                            "supported": [{
                                    "name": "exampleProperty"
                                }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Example directive request and response

The following example shows a custom capability directive to your add-on. Alexa sends the directive to your add-on in the same way that Alexa sends pre-built directives.

The following example shows an Alexa response from your add-on that indicates your add-on processed the directive successfully. Include the state of reported properties for your custom capability in the response. If your custom capability defines a custom error response, use that response instead.

Example state reporting

The following example shows a state report that includes the reportable properties of the custom capability.

The following example shows a change report that you proactively send to Alexa when a reportable property of the custom capability changes.

Was this page helpful?

Provide feedback

Last updated: Aug 01, 2026