Implement Smart Home Skill Code

Note: Sign in to the developer console to build or publish your skill.

You implement your smart home skill code as an Amazon Web Services (AWS) Lambda function and connect the function to your skill ID. This function consists of your skill code, configuration information, and an Identity and Access Management (IAM) role that allows Lambda to run the skill code on your behalf. You can write your code in the AWS Lambda console directly or in a development environment appropriate for the programming language that you plan to use to code your skill. You can author a Lambda function in Node.js, Java, Python, C#, Go, Ruby, or PowerShell. Optionally, Lambda functions can store data in AWS DynamoDB and write logs to AWS CloudWatch.

For a step-by-step tutorial to create a simple smart home skill, see Tutorial: Build a Smart Home Skill.

Best practices

Before you add code to your lambda function, review these best practices to implement a smart home skill:

Find the Smart Home Skill APIs appropriate to control your smart home device. Declare all supported capabilities in your discovery response.
Declare the correct version for each interface. Most Alexa interfaces are version 3, not version 3.0.
In every response and event message, set messageId to a unique identifier, preferably a version 4 UUID.
To keep Alexa up-to-date on the state of your device, mark capability properties as retrievable and proactivelyReported in your discovery response. For details, see Alexa.Discovery.
Include manufacturer and model in 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 EndpointHealth. Support as many EndpointHealth properties 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.ChangeReport events when the device state changes for any reason. For details, see Report State in a ChangeReport. Send the report within three seconds of the state change. Include the current value of the connectivity property, defined by the Alexa.EndpointHealth interface.
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.

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 skill might need.

To create a Lambda function, sign in to the AWS management console with your AWS credentials, and then complete the following items:

Create an IAM policy on the IAM Policies page. Add the permissions for the AWS resources that you plan to access from your Lambda function.
Create an IAM role on the IAM Roles page. For Trusted entity type, select AWS service, and then for Common use cases, select Lambda. Add the appropriate policies to the role.
Tip: For Lambda execution and access to AWS CloudWatch logs, you can use the AWSLambdaBasicExecutionRole policy.
Create a Lambda function on the Lambda dashboard. Create your function in the same region where you offer your skill. Later, you can add other languages and regions.
- For Add trigger, select Alexa.
- For Application ID, paste your skill ID.

To copy the ARNs for your Lambda function, at the top of the Lambda > Functions > my-smart-home-skill page, select Copy ARN. You add the ARN for each region when you configure the service endpoint. Alexa accesses the function by the ARN.

For a step-by-step tutorial to create an IAM role and Lambda function, see Smart Home Tutorial Step 2: Implement Skill Code.

AWS Lambda regions

The following table lists the Alexa region where you can deploy your skill and the associated AWS Lambda region to host your skill code. Make sure to create your Lambda function in the appropriate region. This choice means that you reduce latency between Alexa and your skill service.

Skill 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
Arabic (SA), English (IN), English (UK), French (FR), German (DE), Hindi (IN), Italian (IT), Spanish (ES)	EU (Ireland)	Europe and India
English (AU), Japanese	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 Lamba function

On the Lambda > Functions > <your function name> page, select the Configuration tab.
Select General configurations, and then click Edit.
For Memory, increase to at least 256 MB.
For Timeout, set to 0–8 seconds, and then click Save.

Add code to your Lambda function

Alexa converts user utterances into directives with a specific JSON structure. Then, Alexa sends the directives to your skill. Your skill's Lambda code processes the directives and performs the requested action by communicating with your device through your cloud. Your skill 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 skill 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 skill. 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 skill users, your skill code must support the following functionality.

Discovery — To identify the device endpoints associated with the user's Alexa account.
Capability directives — Respond to directives to control the devices.
State reporting — To keep Alexa up-to-date on the status of the devices.
Send asynchronous events — Request access to the Alexa event gateway to send asynchronous responses and state changes.

The following diagram shows the most common communication flow between the customer using the Alexa app, the Alexa service, your skill, and the device. This example uses the Alexa-app account linking authorization code grant flow. For details, see Initiating account linking when enabling the skill.

The customer enables your skill 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. The entire account linking flow isn't shown.
On success, the Alexa service receives an access token (shown as linkedAccountToken) for access to the customer account in your system. Alexa includes the token in subsequent directives to your skill.
Account linking is complete.
The Alexa service starts the Alexa event gateway authorization flow by sending the Alexa.Authorization.AcceptGrant directive to your skill. In response, your skill initiates an authorization code-grant flow between your skill and the Amazon LWA authorization server. Your skill obtains the access token (shown as amazonToken) for the Amazon customer and stores the token in the skill backend. You use this token to send events to the Alexa event gateway.
The customer requests that your skill discover the customer's devices.
The Alexa service sends the Alexa.Discovery.Discover directive to your skill identify the endpoints associated with the user's device account. For each endpoint, your skill includes the device endpoint information and the capabilities of the endpoint in the Discover.Response.
The Alexa service sends the Alexa.ReportState directive to request the current state of the device.
The skill replies with cached state data. Alternatively, the skill might query the device.
The customer turns on your device in the Alexa app.
Alexa sends an Alexa.PowerController.TurnOn directive to your skill. Your skill invokes an API in your device cloud or directly on the device to turn on the device.
The customer turns off the device manually. Your device notifies your skill.
In response, your skill sends an Alexa.ChangeReport to 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 the retrievable 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 example discovery responses, 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 Alexa skill.

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.ReportState directive. You reply with an Alexa.StateReport response 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 a TurnOn directive, you include a snapshot of all property values.
You proactively send an asynchronous Alexa.ChangeReport event to indicate one or more reportable properties changed. In the event, you also include a snapshot of all other property values.

Implement asynchronous events

You send Alexa.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.

This message flow requires that you enable events in the Alexa developer console and obtain access tokens for each customer. For detailed steps to enable asynchronous events in your code, see Send Events to the Alexa Event Gateway.

Tip: Implement and test discovery, capability directives and synchronous responses, and Alexa.StateReport first. After that code works, follow the steps in Send Events to the Alexa Event Gateway to implement asynchronous events.

Configure the service endpoint

To establish the link between Alexa and the Lambda function, you provide the Lambda ARN in the skill 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 skill:

If your skill supports one language and region, provide the same ARN for the default ARN and the selected regional ARN.
If your skill supports multiple languages and regions, you must provide ARNs for each region. Provide one of the regional ARNs for the default ARN.

Tip: Lambda creates a new version of your function each time that you publish the function. You can use the ARN for a specific version, or you can create an alias for a Lambda function version. Use an alias ARN to invoke a different version as you make enhancements to your Lambda function. For more details, see Lambda function aliases.

To configure the service endpoints in the Alexa developer console

Navigate back to your skill 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.
Click SAVE.

Was this page helpful?

Provide feedback

Last updated: Nov 22, 2023