Steps to Build a Smart Home Skill

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

For an overview of smart home skills, see Understand Smart Home Skills. For a step-by-step tutorial to create a simple smart home skill, see Tutorial: Build a Smart Home Skill.

Complete the following steps to build a smart home skill.

Prerequisites

Before you develop a smart home skill, 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 skill code on AWS Lambda.
  • A smart device, such as a light, thermostat, camera, lock, that connects to the device cloud. Your skill 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 skill 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.
  • Appropriate Smart Home Skill APIs for the directives to control your smart home device. For details about the supported locales and languages for Smart Home Skill APIs, see List of Alexa Interfaces and Supported Languages.
  • Familiarity with the skill certification requirements for policy and security.

Create the skill in the developer console

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

You can choose English(US) as your default language and region, or you can create your skill in another language and region. Make sure to select the region where you plan to make your skill available. Language support varies by interface. For details, see List of Alexa Interfaces and Supported Languages.

After you create your skill, 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 skill to your skill code hosted on Lambda.

Create a Lambda function

You implement your skill code as a Lambda function and connect the function to your skill ID. Every Lambda function has an Amazon Resource Name (ARN) that defines the endpoint to invoke the function. Alexa accesses the function by the ARN.

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. Optionally, Lambda functions can store data in AWS DynamoDB and write logs to AWS CloudWatch.

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, Substeps a-c.

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. To discover smart home devices, you create your function in the same region where your devices are located. 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.

      Copy the ARNs for your Lambda function. You add the ARN for each region when you configure the service endpoint.

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)

You can create smart home skills in other languages. For details, see Develop Smart Home Skills for Multiple Languages. Language support varies by interface. For details, see List of Alexa Interfaces and Supported Languages.

Configure the service endpoint

In response to a user utterance, Alexa sends a directive to the smart home skill at the ARN for the Lambda function. To establish the link between Alexa and the Lambda function, you provide the Lambda ARN in the skill configuration in the Alexa developer console. On the Smart Home page, under 2. Smart Home service endpoint, paste the ARN for the Lambda function, and then click SAVE.

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

Implement skill code

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

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

In response to the Alexa.Discovery.Discover directive, 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, such as low battery or loss of connectivity. 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 of the properties that changed. In the event, you also include a snapshot of all other property values.

You send the Alexa.ChangeReport event and asynchronous Alexa.Response messages to the Alexa event gateway. This message flow requires that you enable events in the Alexa developer console and obtain access tokens for each customer. For details, see Send Events to the Alexa Gateway.

Configure account linking

All smart home skills 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 store's the light bulb model and capabilities, such as whether you can dim the bulb. When the user enables your skill 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 skill. The token enables your skill 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 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 skill 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 skill 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 skill 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 skill in the Alexa developer console. On the Smart Home page, from the left menu, click ACCOUNT LINKING. Enter the required information, and then click 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.

Test your skill

As you develop your skill 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 skill and begin testing.

To enable your skill and begin testing

  1. In the Alexa app, enable your skill. Alexa performs account linking, sends an Alexa.Authorization.AcceptGrant to your skill to connect your skill to the user's Amazon account, and then sends an Alexa.Discover request to your skill to discover devices.
  2. If your skill successfully discovers devices, in the developer console, complete the steps to enable your skill for testing.
  3. In the developer console, on the Test tab, test your skill in 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 skill supports. Make sure to test your skill with valid and invalid utterances. To verify change reporting and endpoint health, power your device off and back on.

You can iterate on your skill code and continue testing. If you change the account linking configuration, disable and re-enable the skill 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 skill in the Alexa app. For options to test and debug your skill, see Test and Debug Your Smart Home Skill.

When you're satisfied with your skill, you can provide the skill distribution information.

Configure your skill for distribution

To distribute your skill to the Amazon Alexa Skills Store, you must fill out the required metadata for your skill on the Distribution tab in the developer console.

After you complete and save the skill information, you can distribute your skill for beta testing or submit it for certification. For details, see Smart Home Skill Publishing Guide.

Beta test your skill (optional)

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

Submit your skill for certification

When you're ready to publish your skill, submit for certification. For details about certifying a skill, see Test and Submit Your Skill for Certification.

  • 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 skill.
  • Make sure that your skill meets the Alexa policy guidelines. These guidelines help make sure that your skill is appropriate for all customers. Adherence to these guidelines guards the privacy and welfare of Alexa users.
  • Make sure that your skill meets the Alexa security requirements. Customer trust is important. To protect customer data, your skill must meet these security requirements.

Revise and update your skill after publication

After Amazon publishes your skill to end users, the skill status changes to live. Any changes that you make to the skill configuration and the Lambda function must be recertified. When the skill status changes to live, a new development version is automatically created in the developer console. This version has the same information as the original live version. You make changes to the development version. When you submit your updated skill 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 skill in the developer console.

To change to your Lambda function

  1. Create a new Lambda function with a new ARN.
  2. Copy your live Lambda function skill code to the new Lambda function.
  3. In the new Lambda function, make updates to your skill code.
  4. In the development stage for your skill, update the Lambda ARN configuration to point to the new Lambda function ARN.

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