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. Alexa interprets customer utterances and sends messages to your skill that communicate these requests. In addition, the Smart Home Skill API enables you to display the up-to-date status of configured devices in the Alexa app.

How the Smart Home Skill API Works

A customer enables a smart home skill in the Alexa app, links it to their account with a device cloud and discovers devices associated with that account.

Then, when Alexa hears a customer request like, "Alexa, turn the kitchen light to 50 percent", or a customer makes change to a light setting in the Alexa app, Alexa recognizes the customer intent to change a setting on a specific device. Alexa uses this information to create a message called a directive. This directive contains customer authentication information, an identifier for the device, and the new setting value. Alexa knows to send this message to the smart home skill that controls the light. As a smart home developer, you receive and parse this message in code hosted in AWS Lambda, a compute service offered by Amazon Web Services (AWS), and pass it to the specified device in your device cloud. You respond with a message called an event and indicate the request was successful or not. You have the option of sending the event synchronously from the Lambda function or asynchronously from the device cloud. Alexa uses the information in the event to respond to the customer that made the request.

In addition to supporting voice requests, the API also enables you to easily provide updates when the state of a device changes. This means customers can see an up-to-date status and control their devices from the Alexa app. For example, a customer can use the Alexa app to check the temperature of their home or turn off their lights.

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

  • Device APIsCapability interfaces describe a device’s functionality. A device endpoint can implement the combination of capabilities that best model its features. For example, a light that can be turned on and off and dimmed implements two interfaces: PowerController and BrightnessController. If another light has these two capabilities, and also supports tunable white light, it could implement PowerController, BrightnessController and ColorTemperatureController.
  • Synchronous and Asynchronous Messaging – When a device directive is sent from Alexa, developers respond with an event, either synchronously, or asynchronously when the directive has been handled. 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 – Amazon enables developers to 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 the functionality offered for smart home skill developers.

Smart Home Skill API

For example:

  1. A customer enables a skill and completes the endpoint discovery process.
  2. The customers says, "Alexa, turn on the kitchen light" to their Alexa device or turns on the light in the Alexa app.
  3. Alexa uses information from the customer utterance or the Alexa app to compose a message that identifies the endpoint and the operation to perform. This directive is sent to the skill that controls the kitchen light. The directive includes:
    • The capability (PowerController.TurnOn)
    • The endpoint identifier (an ID representing the endpoint that the customer named "kitchen light")
    • A message identifier
    • Information authenticating the customer
  4. Your skill code, which is hosted as a Lambda function 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 turn on the customer’s kitchen light.
  5. The skill sends a response back to Alexa indicating if the operation was successful. 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.
  6. Later the customer switches off the kitchen light manually and the skill sends a change report event to Alexa that the light is now off.

What Kind of Devices are Supported

You can use the Alexa interfaces specifically designed to enable control of smart home cameras, entertainment devices, lights, locks, and thermostats, but you can also control other smart home devices using broadly applicable primitives: for example, you can use power control interface for turning nearly any smart device on or off, and the percentage control interface for setting intensity or speed. Following is a list of device-specific guidelines, but for a full list of interfaces, see the Smart Home Skill API Message Reference.

Who Can Develop Smart Home Skills for Alexa

Anyone can develop a smart home skill. Developing smart home skills is easy because the complexity of the voice interactions are handled by Amazon. Alexa knows how to interpret the user’s speech and what directives to send to your smart home 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 or lock 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
  • Knowledge of Java, Node.js, C# or Python as  Lambda functions can be written in any of these languages
  • Understanding of OAuth 2.0

Next Steps to Create a Skill

Other Resources