Implement Smart Home Skill Code

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

To create a Lambda function, sign in to the AWS management console with your AWS credentials, and then complete the following steps. If you already have an IAM role with a Lambda basic execution policy attached, skip to the last step.

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

To create a Lambda function

  1. Sign in to the AWS management console.
  2. Create an IAM policy.
    Navigate to the Policies page on the IAM dashboard, and then click Create Policy. Add the permissions for the AWS resources that you plan to access from your Lambda function.
  3. Create an IAM role.
    Navigate to the Roles page on the IAM dashboard, and then click Create Role. For Trusted entity type, select AWS service, and then for Common use cases, select Lambda. Add the policy that you just created to the role.
  4. Create a Lambda function.
    Navigate to the Lambda console, and then select the correct region for your Lambda function. Create your function in the same region where your skill is offered. Later, you can add other languages and regions.
    • For Runtime, choose the programming language of your choice.
    • For Architecture, leave the default.
    • For Permissions > Change default execution role, select Use an existing role, and then select the IAM role that you just created.
    • For Add trigger, select Alexa Smart Home.
    • 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.

AWS Lambda regions

The following table lists the Alexa region where you can deploy your skill and the associated AWS Lambda region that you must use. Make sure to create your Lambda function in the appropriate region.

Endpoint region Skill language AWS Lambda region
North America Arabic (SA), English (CA), English (US), French (CA), Portuguese (BR), Spanish (MX), Spanish (US) US East (N. Virginia)
Europe Arabic (SA), English (UK), French (FR), German, Italian, Spanish (ES) EU (Ireland)
India English (IN), Hindi (IN) EU (Ireland)
Far East English (AU), Japanese US West (Oregon)

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 only account linking authorization code grant flow. For details, see Initiating account linking when enabling the skill.

Click to enlarge
  1. The customer enables your skill in the Alexa app.
  2. 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.
  3. On success, the Alexa service receives an access token (shown in black) for access to the customer account in your system. Alexa includes the token in subsequent directives to your skill.
    Account linking is complete.
  4. 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 in blue) for the Amazon customer and stores the token in the skill backend. You use this token to send events to the Alexa event gateway.
  5. The customer requests that your skill discover the customer's devices.
  6. 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.
  7. 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.
  8. The customer turns on your device in the Alexa app.
  9. 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.
  10. The customer turns off the device manually. Your device notifies your skill.
  11. 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.

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. 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.

To configure the service endpoints in the Alexa developer console

  1. Navigate back to your skill in the Alexa developer console.
  2. On the Smart Home page, under 2. Smart Home service endpoint, for Default endpoint, paste the default ARN for the Lambda function.
  3. 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.
  4. Click SAVE.