Understand the Smart Home Skill API

Smart home skills provide a simple way for you to enable Alexa voice interaction to control and check the status of cloud-connected devices. With smart home skills, the voice interaction model is defined and handled for you, so your skill gets built-in support for many different kinds of devices. Alexa interprets customer utterances and sends messages to your skill that communicate these requests.

How the Smart Home Skill API works

The Smart Home Skill API provides capability interfaces that enable you to describe your devices and the properties, events, and directives that they support. You describe a device to Alexa by sending a Discover.Response event after receiving a Discover directive from Alexa, or by proactively sending an AddOrUpdateReport to Alexa. Alexa uses this description of your device and its capabilities to automatically enable certain functionality, such as:

  • Alexa's native Voice User Interface (VUI) for many common commands.
  • Support for contextual targeting, which lets Alexa use context clues, such as device groups, to issue commands that target the proper device even when the customer isn't explicit.
  • Support for controlling devices through routines.
  • Support for viewing and controlling devices with the Alexa mobile app.

In addition to supporting voice requests, the API also enables you to provide updates when the state of a device changes. This enables customers to ask Alexa about a device and see an up-to-date status of the device in the Alexa app. For example, a customer can use the Alexa app to check the temperature of their home or see if a light is on.

To support these customer scenarios, this API has the following features:

  • Capability interfaces – These interfaces describe a device's functionality. A device, or endpoint, can implement the combination of capability interfaces that best represent its features. For example, a light that can be turned on and off and dimmed might implement two interfaces: PowerController and BrightnessController. A similar light that has these two features and also supports tunable white light might also implement ColorTemperatureController.
  • Synchronous and asynchronous messaging – When Alexa sends a directive, your smart home skill responds with a message, called an event, either synchronously or asynchronously. You are free to choose asynchronous or synchronous responses or a combination of the two, whichever works best for your device and cloud architecture.
  • Device state change notifications – You can provide proactive state updates to Alexa in event messages. Alexa can then provide this information in the Alexa app and enable customers to take action, if needed. For example, if a door unlocks, you can send this change report to Alexa and your customer's Alexa app will automatically show this change.
  • Querying capability – Capability interfaces define properties that Alexa can query, enabling customers to check the current state of a device using Alexa or the Alexa app.

The following image shows an overview of the functionality offered by the Smart Home Skill API.

Alexa Smart Home Skill API overview

For example:

  1. A customer enables your smart home skill, links the skill to his or her account with your device cloud, and asks Alexa to discover devices associated with that account.
  2. Later, when the customers says (for example), "Alexa, turn the kitchen light to 50 percent", or makes a change to a device setting in the Alexa mobile app, Alexa uses information from the customer's utterance or the app to compose a message that identifies the endpoint and the operation to perform. This message, called a directive, is sent to your skill which controls the kitchen light. The directive includes:
    • The capability message (for example, BrightnessController.SetBrightness), which includes the new setting value.
    • The endpoint identifier (an ID representing the endpoint that the customer named "kitchen light").
    • Information authenticating the customer.
  3. Your skill code, which is hosted in AWS Lambda, a compute service offered by Amazon Web Services (AWS), receives and parses the directive, validating the authentication information. Your skill communicates with your systems, or device cloud, using communication channels you've defined, to set the brightness on the customer's kitchen light.
  4. Your skill responds to Alexa with a message called an event that indicates whether the operation was successful. You have the option of sending the event synchronously from the Lambda function or asynchronously from the device cloud. Alexa uses this response to provide the appropriate response to the customer. For example, Alexa might say, "OK" to indicate the requested directive was successfully handled.
  5. Later the customer switches off the kitchen light manually, which causes your skill to send a change report event to Alexa to indicate that the light is now off.

What kinds of devices are supported

With the Alexa Smart Home Skill API, you can build a skill that connects a wide variety of internet-connected devices to Alexa. Many capability interfaces are specific to a particular kind of device, but others apply to many kinds of devices. For example, the ThermostatController interface is specific to thermostats, but interfaces like PowerController, ModeController, RangeController, and ToggleController can apply to many kinds of devices.

Whenever possible, choose an interface that is specific to your device because that enables Alexa to support more specific functionality. For example, you could model the concept of device brightness with BrightnessController, PercentageController, or RangeController, but Alexa provides built-in voice support for the phrase "Alexa, dim the lights" only when you use BrightnessController.

For most of the interfaces, you can use only one interface per device. For example, a device can have only one PowerController. However, a device can have more than one of the following interfaces:

  • ModeController
  • RangeController
  • ToggleController

For examples that show how you can represent a variety of devices with the smart home capability interfaces, get started with device templates. For conceptual information about some of the categories of devices that you can represent, see the following topics about building smart home skills for:

For the complete list of capability interfaces and some example utterances that each one supports, see the list of capability interfaces.

In addition to using the built-in support for devices that's provided by the Smart Home Skill API, you can add custom voice interaction to your skill to customize the Alexa experience for your customers. To do this, use the CustomIntent interface. For more information, see Add Custom Voice Interaction to a Smart Home Skill. This feature is currently available in preview. To request access to the preview, fill out this survey.

Who can develop smart home skills for Alexa

Anyone can develop a smart home skill. With the Smart Home Skill API, the voice interactions are defined for you which means that Alexa knows how to interpret the user's speech and what directives to send to your skills. Generally, smart home skill development falls into two categories:

  • Developers who represent cloud-connected device manufacturers that want to enable customers to interact with those devices using their voice.
  • Independent developers who want to create an Alexa skill for cloud-connected devices, either for their own private use or general public use (certification required for public use).

Prerequisites to smart home skill development

In order to develop a smart home skill you must have the following:

  • An Amazon developer account. Sign up is free.
  • A connected device such as a light, thermostat, camera, lock, or other device with a cloud API to control it.
  • An Alexa-enabled device such as Amazon Echo.
  • An AWS account. You host your skill code in an AWS Lambda function.
  • Knowledge of JSON and one of the supported languages for AWS Lambda: Node.js, Java, Python, C#, or Go.
  • Understanding of OAuth 2.0.

Next steps to create a skill

To get started, see steps to build a smart home skill.

For an overview of other kinds of Alexa skills that you can build with the Alexa Skills Kit, see understanding the different skill models.

Other resources

For help, try the following resources: