Steps to Build Smart Home Add-ons

When you create a smart home add-on, you enable Alexa to invoke your add-on to fulfill a user request to control a smart home device. Smart home add-ons use the pre-built voice interaction model and Alexa defines the set of utterances for you. You can create an Alexa smart home add-on for most device types.

For an overview of smart home add-ons, see Connect Your Device Cloud with Smart Home Add-ons. For a step-by-step tutorial to create a smart home add-on that controls a virtual light bulb, see Tutorial: Build a Smart Home Add-on.

Complete the following steps to build a smart home add-on.

Prerequisites

Before you develop a smart home add-on, make sure that you have the following items:

• An Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
• An Amazon Web Services (AWS) account. The AWS account gives you access to resources as part of the free tier of services. You host your add-on code on AWS Lambda.
• A smart device, such as a light, thermostat, camera, lock, that connects to the device cloud. Your add-on communicates with your device, or device cloud, by using communication channels supported by your device.
• An Alexa-enabled device, such as an Amazon Echo. Make sure that you sign in to the Echo with the same credentials as your Alexa developer account.
• The Amazon Alexa app on your mobile device. For instructions about how to download the Alexa app, see Download the Alexa app on the Amazon website. Make sure that you sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.
• Knowledge of JSON and one of the supported programming languages for AWS Lambda add-on code: Node.js, Java, Python, C#, Go, Ruby, or PowerShell.
• An OAuth 2.0 provider for account linking. You can use the Amazon authorization server, called Login with Amazon (LWA), or you can choose your own OAuth 2.0 provider.
• A device cloud that interacts with your devices and can associate customers with their devices. You can use AWS IoT or your own cloud provider.
• Appropriate Smart Home APIs for the directives to control your smart home device. For details about the supported locales and languages, see List of Alexa Interfaces and Supported Languages.
• Familiarity with the certification requirements for policy and security.

Steps to build a smart home add-on

To build a smart home add-on, complete the following steps:

1. Choose Alexa capabilities
2. Create a smart home add-on.
3. Implement add-on code.
4. Configure account linking.
5. Test your add-on.
6. Provide publishing information.
7. Beta test your add-on (optional).
8. Submit your add-on for certification.

Step 1: Choose Alexa capabilities

Before you start, review the Alexa interface reference to find the appropriate capability interfaces to control your smart home device. For details about supported interfaces and languages, see List of Alexa Interfaces and Supported Languages.

You can choose from the large set of standard capability interfaces, such as Alexa.BrightnessController and Alexa.PowerController, or general-purpose interfaces to model components of your device, like Alexa.ModeController and Alexa.RangeController. When these capabilities don't suffice, you can implement fully customizable, device-specific capability interfaces to take advantage of the unique features of your device. You add the custom capability to your code in the same way as pre-built interfaces. For details, see Add Custom Capabilities.

Step 2: Create a smart home add-on

You create a smart home add-on in the Alexa developer console. When prompted to choose a model to add to your add-on, select the Smart Home model.

You can choose English(US) as your default language and region, or you can create your add-on in another language and region. Make sure to select the region where you plan to make your add-on available. You can create your add-on in other languages. For details, see Develop Smart Home Add-ons for Multiple Languages. Language support varies by interface. For more details, see List of Alexa Interfaces and Supported Languages.

After you create your add-on, copy the skill ID to a convenient place, such as Notepad on Windows or TextEdit on Mac. You use the skill ID to connect your add-on to your add-on code hosted on Lambda.

Step 3: Implement add-on code

You implement your smart home add-on code as an Amazon Web Services (AWS) Lambda function. For more details, see Implement Smart Home Add-on Code. If applicable, you can add additional features to your add-on.

Example add-on code

The following smart home add-on code example controls a light bulb.

Example add-on code  

// -*- coding: utf-8 -*-

// Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//
// SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
// Licensed under the Amazon Software License (the "License")
// You may not use this file except in compliance with the License.
// A copy of the License is located at http://aws.amazon.com/asl/
//
// This file is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific
// language governing permissions and limitations under the License.

exports.handler = function (request, context) {
    if (request.directive.header.namespace === 'Alexa.Discovery' && request.directive.header.name === 'Discover') {
        log("DEBUG:", "Discover request",  JSON.stringify(request));
        return handleDiscovery(request, context, "");
    }
    else if (request.directive.header.namespace === 'Alexa.PowerController') {
        if (request.directive.header.name === 'TurnOn' || request.directive.header.name === 'TurnOff') {
            log("DEBUG:", "TurnOn or TurnOff Request", JSON.stringify(request));
            return handlePowerControl(request, context);
        }
    }
    else if (request.directive.header.namespace === 'Alexa.Authorization' && request.directive.header.name === 'AcceptGrant') {
        return handleAuthorization(request, context)
    }

    function handleAuthorization(request, context) {
        // Send the AcceptGrant response
        var payload = {};
        var header = request.directive.header;
        header.name = "AcceptGrant.Response";
        log("DEBUG", "AcceptGrant Response: ", JSON.stringify({ header: header, payload: payload }));
        return { event: { header: header, payload: payload } };
    }

    function handleDiscovery(request, context) {
        // Send the discovery response
        var payload = {
            "endpoints":
            [
                {
                    "endpointId": "sample-bulb-01",
                    "manufacturerName": "Smart Device Company",
                    "friendlyName": "Livingroom lamp",
                    "description": "Virtual smart light bulb",
                    "displayCategories": ["LIGHT"],
                    "additionalAttributes":  {
                        "manufacturer" : "Sample Manufacturer",
                        "model" : "Sample Model",
                        "serialNumber": "U11112233456",
                        "firmwareVersion" : "1.24.2546",
                        "softwareVersion": "1.036",
                        "customIdentifier": "Sample custom ID"
                    },
                    "cookie": {
                        "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
                        "key2": "There can be multiple entries",
                        "key3": "but they should only be used for reference purposes.",
                        "key4": "This is not a suitable place to maintain current endpoint state."
                    },
                    "capabilities":
                    [
                        {
                            "interface": "Alexa.PowerController",
                            "version": "3",
                            "type": "AlexaInterface",
                            "properties": {
                                "supported": [{
                                    "name": "powerState"
                                }],
                                 "retrievable": true
                            }
                        },
                        {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                    ]
                }
            ]
        };
        var header = request.directive.header;
        header.name = "Discover.Response";
        log("DEBUG", "Discovery Response: ", JSON.stringify({ header: header, payload: payload }));
        return { event: { header: header, payload: payload } };
    }

    function log(message, message1, message2) {
        console.log(message + message1 + message2);
    }

    function handlePowerControl(request, context) {
        // get device ID passed in during discovery
        var requestMethod = request.directive.header.name;
        var responseHeader = request.directive.header;
        responseHeader.namespace = "Alexa";
        responseHeader.name = "Response";
        responseHeader.messageId = responseHeader.messageId + "-R";
        // get user token pass in request
        var requestToken = request.directive.endpoint.scope.token;
        var powerResult;

        if (requestMethod === "TurnOn") {

            // Make the call to your device cloud for control
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "ON";
        }
       else if (requestMethod === "TurnOff") {
            // Make the call to your device cloud for control and check for success
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "OFF";
        }
        // Return the updated powerState.  Always include EndpointHealth in your Alexa.Response
        // Datetime format for timeOfSample is ISO 8601, `YYYY-MM-DDThh:mm:ssZ`.
        var contextResult = {
            "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": powerResult,
                "timeOfSample": "2022-09-03T16:20:50.52Z", //retrieve from result.
                "uncertaintyInMilliseconds": 50
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                "value": "OK"
            },
            "timeOfSample": "2022-09-03T22:43:17.877738+00:00",
            "uncertaintyInMilliseconds": 0
            }]
        };
        var response = {
            context: contextResult,
            event: {
                header: responseHeader,
                endpoint: {
                    scope: {
                        type: "BearerToken",
                        token: requestToken
                    },
                    endpointId: "sample-bulb-01"
                },
                payload: {}
            }
        };
        log("DEBUG", "Alexa.PowerController ", JSON.stringify(response));
         return response;
    }
};

# -*- coding: utf-8 -*-

# Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
# Licensed under the Amazon Software License (the "License")
# You may not use this file except in
# compliance with the License. A copy of the License is located at http://aws.amazon.com/asl/
#
# This file is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific
# language governing permissions and limitations under the License.


import json
import math
import random
import uuid
import logging
import datetime
from datetime import datetime, timezone

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

def lambda_handler(request, context):

    # Dump the request for logging - check the CloudWatch logs.
    print('lambda_handler request  -----')
    print(json.dumps(request))


    if context is not None:
        print('lambda_handler context  -----')
        print(context)

    # Validate the request is an Alexa smart home directive.
    if 'directive' not in request:
        alexa_response = AlexaResponse(
            name='ErrorResponse',
            payload={'type': 'INVALID_DIRECTIVE',
                     'message': 'Missing key: directive, Is the request a valid Alexa Directive?'})
        return send_response(alexa_response.get())

    # Check the payload version.
    payload_version = request['directive']['header']['payloadVersion']
    if payload_version != '3':
        alexa_response = AlexaResponse(
            name='ErrorResponse',
            payload={'type': 'INTERNAL_ERROR',
                     'message': 'This skill only supports Smart Home API version 3'})
        return send_response(alexa_response.get())

    # Crack open the request to see the request.
    name = request['directive']['header']['name']
    namespace = request['directive']['header']['namespace']

    # Handle the incoming request from Alexa based on the namespace.
    if namespace == 'Alexa.Authorization':
        if name == 'AcceptGrant':
            # Note: This example code accepts any grant request.
            # In your implementation, invoke Login With Amazon with the grant code to get access and refresh tokens.
            grant_code = request['directive']['payload']['grant']['code']
            grantee_token = request['directive']['payload']['grantee']['token']
            auth_response = AlexaResponse(namespace='Alexa.Authorization', name='AcceptGrant.Response')
            return send_response(auth_response.get())

    if namespace == 'Alexa.Discovery':
        if name == 'Discover':
            # The request to discover the devices the skill controls.
            discovery_response = AlexaResponse(namespace='Alexa.Discovery', name='Discover.Response')
            # Create the response and add the light bulb capabilities.
            capability_alexa = discovery_response.create_payload_endpoint_capability()
            capability_alexa_powercontroller = discovery_response.create_payload_endpoint_capability(
                interface='Alexa.PowerController',
                supported=[{'name': 'powerState'}])
            capability_alexa_endpointhealth = discovery_response.create_payload_endpoint_capability(
                interface='Alexa.EndpointHealth',
                supported=[{'name': 'connectivity'}])
            discovery_response.add_payload_endpoint(
                friendly_name='Sample Light Bulb',
                endpoint_id='sample-bulb-01',
                capabilities=[capability_alexa, capability_alexa_endpointhealth, capability_alexa_powercontroller])
            return send_response(discovery_response.get())

    if namespace == 'Alexa.PowerController':
        # The directive to TurnOff or TurnOn the light bulb.
        # Note: This example code always returns a success response.
        endpoint_id = request['directive']['endpoint']['endpointId']
        power_state_value = 'OFF' if name == 'TurnOff' else 'ON'
        correlation_token = request['directive']['header']['correlationToken']

        # Check for an error when setting the state.
        device_set = update_device_state(endpoint_id=endpoint_id, state='powerState', value=power_state_value)
        if not device_set:
            return AlexaResponse(
                name='ErrorResponse',
                payload={'type': 'ENDPOINT_UNREACHABLE', 'message': 'Unable to reach endpoint database.'}).get()

        directive_response = AlexaResponse(correlation_token=correlation_token)
        directive_response.add_context_property(namespace='Alexa.PowerController', name='powerState', value=power_state_value)
        return send_response(directive_response.get())

# Send the response
def send_response(response):
    print('lambda_handler response -----')
    print(json.dumps(response))
    return response

# Make the call to your device cloud for control
def update_device_state(endpoint_id, state, value):
    attribute_key = state + 'Value'
    # result = stubControlFunctionToYourCloud(endpointId, token, request);
    return True

# Datetime format for timeOfSample is ISO 8601, `YYYY-MM-DDThh:mm:ssZ`.
def get_utc_timestamp(seconds=None):
    return datetime.now(timezone.utc).isoformat()

class AlexaResponse:

    def __init__(self, **kwargs):

        self.context_properties = []
        self.payload_endpoints = []

        # Set up the response structure.
        self.context = {}
        self.event = {
            'header': {
                'namespace': kwargs.get('namespace', 'Alexa'),
                'name': kwargs.get('name', 'Response'),
                'messageId': str(uuid.uuid4()),
                'payloadVersion': kwargs.get('payload_version', '3')
            },
            'endpoint': {
                "scope": {
                    "type": "BearerToken",
                    "token": kwargs.get('token', 'INVALID')
                },
                "endpointId": kwargs.get('endpoint_id', 'INVALID')
            },
            'payload': kwargs.get('payload', {})
        }

        if 'correlation_token' in kwargs:
            self.event['header']['correlation_token'] = kwargs.get('correlation_token', 'INVALID')

        if 'cookie' in kwargs:
            self.event['endpoint']['cookie'] = kwargs.get('cookie', '{}')

        # No endpoint property in an AcceptGrant or Discover request.
        if self.event['header']['name'] == 'AcceptGrant.Response' or self.event['header']['name'] == 'Discover.Response':
            self.event.pop('endpoint')

    def add_context_property(self, **kwargs):
        self.context_properties.append(self.create_context_property(**kwargs))
        self.context_properties.append(self.create_context_property())


    def add_cookie(self, key, value):

        if "cookies" in self is None:
            self.cookies = {}

        self.cookies[key] = value

    def add_payload_endpoint(self, **kwargs):
        self.payload_endpoints.append(self.create_payload_endpoint(**kwargs))


    def create_context_property(self, **kwargs):
        return {
            'namespace': kwargs.get('namespace', 'Alexa.EndpointHealth'),
            'name': kwargs.get('name', 'connectivity'),
            'value': kwargs.get('value', {'value': 'OK'}),
            'timeOfSample': get_utc_timestamp(),
            'uncertaintyInMilliseconds': kwargs.get('uncertainty_in_milliseconds', 0)
        }

    def create_payload_endpoint(self, **kwargs):
        # Return the proper structure expected for the endpoint.
        # All discovery responses must include the additionAttributes
        additionalAttributes = {
            'manufacturer': kwargs.get('manufacturer', 'Sample Manufacturer'),
            'model': kwargs.get('model_name', 'Sample Model'),
            'serialNumber': kwargs.get('serial_number', 'U11112233456'),
            'firmwareVersion': kwargs.get('firmware_version', '1.24.2546'),
            'softwareVersion': kwargs.get('software_version', '1.036'),
            'customIdentifier': kwargs.get('custom_identifier', 'Sample custom ID')
        }

        endpoint = {
            'capabilities': kwargs.get('capabilities', []),
            'description': kwargs.get('description', 'Smart Home Tutorial: Virtual smart light bulb'),
            'displayCategories': kwargs.get('display_categories', ['LIGHT']),
            'endpointId': kwargs.get('endpoint_id', 'endpoint_' + "%0.6d" % random.randint(0, 999999)),
            'friendlyName': kwargs.get('friendly_name', 'Sample light'),
            'manufacturerName': kwargs.get('manufacturer_name', 'Sample Manufacturer')
        }

        endpoint['additionalAttributes'] = kwargs.get('additionalAttributes', additionalAttributes)
        if 'cookie' in kwargs:
            endpoint['cookie'] = kwargs.get('cookie', {})

        return endpoint

    def create_payload_endpoint_capability(self, **kwargs):
        # All discovery responses must include the Alexa interface
        capability = {
            'type': kwargs.get('type', 'AlexaInterface'),
            'interface': kwargs.get('interface', 'Alexa'),
            'version': kwargs.get('version', '3')
        }
        supported = kwargs.get('supported', None)
        if supported:
            capability['properties'] = {}
            capability['properties']['supported'] = supported
            capability['properties']['proactivelyReported'] = kwargs.get('proactively_reported', False)
            capability['properties']['retrievable'] = kwargs.get('retrievable', False)
        return capability

    def get(self, remove_empty=True):

        response = {
            'context': self.context,
            'event': self.event
        }

        if len(self.context_properties) > 0:
            response['context']['properties'] = self.context_properties

        if len(self.payload_endpoints) > 0:
            response['event']['payload']['endpoints'] = self.payload_endpoints

        if remove_empty:
            if len(response['context']) < 1:
                response.pop('context')

        return response

    def set_payload(self, payload):
        self.event['payload'] = payload

    def set_payload_endpoint(self, payload_endpoints):
        self.payload_endpoints = payload_endpoints

    def set_payload_endpoints(self, payload_endpoints):
        if 'endpoints' not in self.event['payload']:
            self.event['payload']['endpoints'] = []

        self.event['payload']['endpoints'] = payload_endpoints

Step 4: Configure account linking

All smart home add-ons must enable account linking to connect the identity of the Alexa user with the user's identity in your system. For a light bulb, your system might have a user account that stores the light bulb model and capabilities, such as whether you can dim the bulb. When the user enables your add-on in the Alexa app, Alexa starts the account linking process and receives an access token from your system. Later, when the user asks Alexa to dim the light bulb, Alexa sends the access token to your add-on. The token enables your add-on to access the user's account in your system to know whether their light bulb is dimmable.

Alexa uses OAuth 2.0 authorization code grant type for smart home add-ons and video skills. To configure account linking, you need the following information from your OAuth provider. For details about these fields, see Configure an Authorization Code Grant.

• URI of the login page on your authorization server — When a customer enables your add-on in the Alexa app, Alexa redirects the customer to this URI to enter login credentials. On successful login, the server returns an authorization code to Alexa.
• URI of your access token server — Endpoint of your authorization server that can exchange an authorization code for access tokens.
• Client ID — Unique string that identifies the add-on that makes requests to your resource server on behalf of the Alexa user.
• Your client secret — Alexa uses the client ID and client secret to authenticate with the Access token URI. These credentials identify the request from Alexa.
• Authentication scheme — Identifies the type of authentication that Alexa uses to request access and refresh tokens from your access token server.
• Scope — (Optional) List of credentials to request from the add-on user, such as user id and password. You can provide up to 15 scopes.
• Domains — (Optional) List of domains that the authorization server requests content from. You can provide up to 30 domains.
• Default access token expiration — (Optional) If your server doesn't provide the expiration time for access tokens in the messaging, you must provide the number of seconds for which the access token is valid.

You configure the authorization server and security profile for the add-on in the Alexa developer console. On the Smart Home page, from the left menu, select ACCOUNT LINKING. Enter the required information, and then choose Save. You can see the redirection endpoints that Alexa uses in the Alexa Redirect URLs field. Register these redirection URLs with your authorization server.

You can use the Amazon OAuth authorization server, called Login with Amazon (LWA) or your own OAuth 2.0 provider. For details about how to set up account linking with the LWA authorization server, see Smart Home Tutorial Step 4: Set up Account Linking.

Step 5: Test your add-on

As you develop your add-on code, you can create test cases in the Lambda console to test the request from Alexa. For details, see Smart Home Tutorial: Step 2e: Test Your Lambda Function.

When your implementation is complete, you can enable your add-on and begin testing.

To enable your add-on and begin testing

1. In the Alexa app, enable your add-on. Alexa performs account linking, sends an Alexa.Authorization.AcceptGrant to your add-on to connect your add-on to the user's Amazon account, and then sends an Alexa.Discover request to your add-on to discover devices.
2. If your add-on successfully discovers devices, complete the steps to enable your add-on for testing in the Alexa developer console.
3. In the developer console, on the Test tab, test your add-on by using the Alexa Simulator.
   Give Alexa commands using the friendly names found in your discovery response and in the Alexa app. Use utterances specific to the device capabilities that your add-on supports. Make sure to test your add-on with valid and invalid utterances. To verify change reporting and endpoint health, power your device off and back on.
4. To debug issues, in the CloudWatch console, find the logs in the log group for your add-on.

You can iterate on your add-on code and continue testing. If you change the account linking configuration, disable and re-enable the add-on in the Alexa app to test the new changes. If you change your discover response code, make sure that you disable and re-enable your add-on in the Alexa app. For options to test and debug your add-on, see Test and Debug Your Smart Home Add-on.

When you're satisfied with your add-on, you can provide the add-on distribution information.

Step 6: Provide publishing information

To distribute your add-on to the Amazon Alexa Skills Store, you must fill out the required metadata for your add-on on the Distribution tab in the developer console. Make sure that you provide links to a privacy policy and terms of use page and that all links open and display properly on iOS, Android, and desktop devices.

After you complete and save the add-on information, you can distribute your add-on for beta testing or submit it for certification.

Step 7: Beta test your add-on (optional)

You have the option to set up a beta test for your add-on. With a beta test, you make your add-on available to a limited group of testers that you personally select, rather than to the public. For details, see Beta Testing.

Step 8: Submit your add-on for certification

Before you submit your add-on for certification, review the Smart Home Certification Guide.

When you're ready to publish your add-on, submit for certification. For details about certifying an add-on, see Submit for Certification in the Alexa Developer Console.

To submit your add-on for certification

1. Run the validation tests on the Certification page in the developer console. These tests help you identify issues that you must fix before you submit the add-on.
2. Make sure that your add-on meets the Alexa+ policy guidelines. These guidelines help make sure that your add-on is appropriate for all customers. Adherence to these guidelines guards the privacy and welfare of Alexa users.
3. Make sure that your add-on meets the Alexa+ security requirements. Customer trust is important. To protect customer data, your add-on must meet these security requirements.
4. When you're ready to publish your add-on, and you verified that your add-on meets the policy and security requirements, submit your add-on for certification.

Add additional features to your add-on

If your device supports inventory sensors, you can add the Amazon Dash replenishment service to your smart home device to enable Alexa to monitor and reorder supplies or replacement parts for your device. For details, see About Dash Replenishment.

Revise and update your add-on after publication

After Amazon publishes your add-on to end users, the add-on status changes to live and a new development version is created in the developer console automatically. This version has the same information as the original live version. Any changes that you make to the add-on configuration or the Lambda function must be certified. When you submit your updated add-on to the developer console, in the Testing Instructions field, add a change log that provides a detailed description of all changes. For details, see Revise and update your add-on in the developer console.

To make changes to your Lambda function

1. Create a new Lambda function with a new ARN.
2. Copy your live Lambda function add-on code to the new Lambda function.
3. In the new Lambda function, make updates to your add-on code.
4. In the development stage for your add-on, update the Lambda ARN configuration to point to the new Lambda function ARN, and then submit your add-on for certification.

After Amazon certifies your updated add-on, Alexa sends requests to the new Lambda ARN. You can deprecate the previous Lambda function or use the function for future development or updates.

Related topics

• Manage Skills in the Developer Console
• Alexa Interface Reference
• Add Account Linking
• Account Linking for Smart Home and Other Domains

Last updated: May 01, 2026