Create a Lambda function
Your Lambda function requires an IAM role that allows basic Lambda function execution and access to other AWS resources that your add-on might need. To create a Lambda function, sign in to the AWS Management Console with your AWS credentials, and then complete the following tasks:-
Create an IAM role on the IAM Roles page.
- For Trusted entity type, select AWS service, and then for Use cases, select Lambda.
- For Add permissions, add the appropriate policies to the role.
- On the Name, review, and create page, for Role name, enter a name, and then choose Create role.
-
Create a Lambda function on the Lambda console. Create your function in the same region where you offer your add-on. Later, you can add other languages and regions.
- For Trigger configuration, select Alexa.
- For Choose an Alexa product, select Alexa Smart Home.
- For SkillID, paste your skill ID.
- To copy the Amazon Resource Name (ARN) for your Lambda function, at the top of the Lambda > Functions page, select Copy ARN. You add the ARN for each region when you configure the service endpoint. Alexa accesses the function by the ARN.
AWS Lambda regions
The following table lists the Alexa region where you can deploy your add-on and the associated AWS Lambda region to host your add-on code. Make sure to create your Lambda function in the appropriate region. Creating your function in the matching region reduces latency between Alexa and your add-on service.| Add-on language and locale | AWS Lambda region | Alexa endpoint region |
|---|---|---|
| Arabic (SA), English (CA), English (US), French (CA), Portuguese (BR), Spanish (MX), Spanish (US) | US East (N. Virginia) | North America |
| Dutch (NL), English (IN), English (UK), French (FR), German (DE), Hindi (IN), Italian (IT), Spanish (ES) | Europe (Ireland) | Europe and India |
| English (AU), Japanese (JP) | US West (Oregon) | Far East and Australia |
Configure your Lambda function
To optimize performance, configure the following operational values. For more details, see Performance optimization. To configure your Lambda function- On the Lambda > Functions > <your function name> page, select the Configuration tab.
- Select General configuration, and then choose Edit.
- For Memory, increase to at least 256 MB.
- For Timeout, set a value of 8 seconds or less, and then choose Save.
Handle Alexa directives in your add-on code
Alexa converts user utterances into directives with a specific JSON structure. Then, Alexa sends the directives to your add-on. Your add-on’s Lambda code processes the directives and performs the requested action by communicating with your device through your cloud. Your add-on code sends responses back to Alexa that indicate success or failure of the request. The response includes the current state of the device. You can author your add-on code in the languages supported for Lambda functions: Node.js, Java, Python, C#, Go, Ruby, or PowerShell. For non-compiled programming languages, such as Python and Node.js, you can write your code in the code editor in the Lambda console. Alternatively, you can use a development environment appropriate for the programming language that you plan to use to implement your add-on. If you write your code in a separate development environment, copy and paste it into the Lambda console editor or upload the code in a zip or jar file. For details, see Getting started with Lambda. To provide the best experience to your add-on users, your add-on code must support the following functionality:- Discovery – Identify the device endpoints associated with the user’s Alexa account.
- Capability directives – Respond to directives to control the devices.
- State reporting – Keep Alexa up to date on the state of the devices.
- Asynchronous events – Request access to the Alexa event gateway to send asynchronous responses and proactive state changes.
- The customer enables your add-on in the Alexa app.
- The Alexa service starts the account linking flow by redirecting the customer to the login page on your device-cloud authorization server. For details, see Configure an Authorization Code Grant.
- On success, the Alexa service receives an access token for access to the customer account in your system. Alexa includes the token in subsequent directives to your add-on.
Account linking is complete. - The Alexa service starts the Alexa event gateway authorization flow by sending the
Alexa.Authorization.AcceptGrantdirective to your add-on. In response, your add-on initiates an authorization code grant flow between your add-on and the Login with Amazon (LWA) authorization server. Your add-on obtains the access_token for the Amazon customer and stores the token on your server. You use this token to send events to the Alexa event gateway. - The customer requests that your add-on discover the customer’s devices.
- The Alexa service sends the
Alexa.Discovery.Discoverdirective to your add-on to identify the endpoints associated with the user’s device account. For each endpoint, your add-on includes the device endpoint information and the capabilities of the endpoint in theDiscover.Response. - The Alexa service sends the
Alexa.ReportStatedirective to request the current state of the device.
The add-on queries the device or replies with recent cached state data. - The customer turns on your device in the Alexa app.
- Alexa sends an
Alexa.PowerController.TurnOndirective to your add-on. Your add-on calls an API in your device cloud or directly on the device to turn on the device. - The customer turns off the device manually.
- In response, your device cloud sends an
Alexa.ChangeReportto the Alexa service to notify Alexa of the state change. The Alexa service updates the state of the device in the Alexa app.
Implement discovery
Implement discovery to inform Alexa about the capabilities of the customer’s connected devices. For more details, see About Alexa Discovery. In your discovery response, you include the endpoint identification information and the capabilities of each endpoint associated with the user’s device account. For available Alexa capability interfaces, see List of Alexa Interfaces. For each capability interface, indicate your support for state reporting by setting theretrievable and proactivelyReported properties to true. Make sure to include support for Alexa.EndpointHealth so that Alexa can notify the user when a device experiences a health issue. You use Alexa.EndpointHealth to report the connectivity status of your device to Alexa as either OK or UNREACHABLE. You can also report other health states, such as battery health. Also, you must include the Alexa interface for all endpoints.
For discovery response examples, see the documentation for each interface that you support.
Implement capability directives
For each endpoint capability that you include in your discovery response, Alexa might send a directive in response to a user request to control the device. Respond promptly to the directives and include the state of all device capabilities in your responses. For details about the directives, see the documentation for each interface that you support in your add-on. Each directive includes an access token in thescope object. Use this token to access the customer data in your system.
Implement state reporting
Implement state reporting so that Alexa knows the current state of your device. For details about state reporting, see Understand State Reporting. You report state to Alexa in three ways:- Alexa requests the state with an
Alexa.ReportStatedirective. You reply with anAlexa.StateReportresponse that includes a snapshot of all property values. - You proactively send the state of all properties in a directive
Alexa.Response. For example, when you respond to aTurnOndirective, you include a snapshot of all property values. - You proactively send an asynchronous
Alexa.ChangeReportevent to indicate that one or more reportable properties changed. In the event, you also include a snapshot of all other property values.
Implement asynchronous events
You sendAlexa.ChangeReport and asynchronous Alexa.Response events to the Alexa event gateway directly from your device cloud or Lambda function. In addition, some interfaces define other events that you send to the event gateway.
To enable asynchronous events in your code, configure the Send Alexa Events permission in the Alexa developer console. For details, see Configure Permissions to Send Events.
Example smart home add-on code
The following add-on code example controls a light bulb and supports the AcceptGrant, Discovery, TurnOn, and TurnOff directives for a virtual light bulb.Example add-on code
Example add-on code
- Node.js
- Python
Deploy your Lambda function
Complete the following steps to add your code to your Lambda function.- On the Lambda > Functions page, open your function.
- To view the code editor, select the Code tab, and then open the file to add the code, such as index.js for Node.js or lambda_function.py for Python.
- In the Code source pane, paste the code into the code editor, replacing any existing code.
- To build and load the function, under DEPLOY, choose Deploy.
Configure the service endpoint
To establish the link between Alexa and the Lambda function, you provide the Lambda ARN in the add-on configuration in the Alexa developer console. For more details, see Deploy your Lambda function to multiple regions. Configure the service endpoints based on the language and region for your add-on:- If your add-on supports one language and region, provide the same ARN for the default ARN and the selected regional ARN.
- If your add-on supports multiple languages and regions, you must provide ARNs for each region. Provide one of the regional ARNs for the default ARN.
- Navigate back to your add-on in the Alexa developer console.
- On the Smart Home page, under 2. Smart Home service endpoint, for Default endpoint, paste the default ARN for the Lambda function.
- For Pick a geographical region that is closest to your target customers and setup geographic specific endpoints, select the regions where your Lambda function resides, and then paste the regional ARNs.
- Choose SAVE.
Best practices
As you write your add-on code, apply these best practices:- Declare all supported capability interfaces in your discovery response.
- Declare the correct version for each interface. Most Alexa interfaces are version
3, not version3.0. - In every response and event message, set
messageIdto a unique ID, preferably a version 4 UUID. - To keep Alexa up to date on the state of your device, mark capability properties as
retrievableandproactivelyReportedin your discovery response. For details, seeAlexa.Discovery. - Include
manufacturerandmodelin the additionalAttributes object in your discovery response. To enable Alexa to identify unique devices, include as many other attributes as you can. - To let Alexa know the health of your device, implement
Alexa.EndpointHealth. Support as manyEndpointHealthproperties as you can. - Report the state of your device on every response to a control directive. For details, see Report state in an Alexa.Response.
- Proactively report the state of your device to Alexa by sending
Alexa.ChangeReportevents when the device state changes for any reason. For details, see Report State in a ChangeReport. - To make sure that Alexa shows the correct state of every property, update the
timeOfSamplevalue only when the property value changes on the device - Send the
Alexa.ChangeReportwithin three seconds of the state change. Include the current value of theconnectivityproperty, defined by theAlexa.EndpointHealthinterface. - If your device has a mobile app for setup, implement account linking from your app to the Alexa app. Your app should support both iOS and Android. For details, see App-to-App Account Linking.
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.Related topics
- Steps to Build Smart Home Add-ons
- Create and Configure a Smart Home Add-on
- Alexa Interface Reference
- Develop Smart Home Add-ons for Multiple Languages
- Discovery Response Examples
- Smart Home Device Templates
- WWA Certification Requirements for Specific Device Types
- Account Linking for Smart Home and Other Domains

