Provide Scenes in a Smart Home Skill

With the scene feature, a customer can use their voice to set multiple devices to previously configured settings. For example, a customer could say, "Alexa, turn on bedtime" and the lights would dim and the temperature decrease for the room. Typically a customer edits and creates scenes with an Alexa-compatible hub or through a device manufacturer's app. A customer can then discover these scenes with their Alexa-enabled device.

Providing a skill that supports a scene is very similar to how you provide a smart home skill for any other connected device, however there are some special requirements for your skill adapter. To enable the scene functionality for a smart home skill, your skill adapter code must:

  • Enable discovery of a scene that affects settings on allowed devices only
  • Ensure certain properties of the discovery response are formatted correctly for a scene
  • Expose 12 or less scenes in the discovery process

Prerequisites

If you haven't created a smart home skill in the past, you should review the existing documentation as a prerequisite to this document.

Scene discovery and allowed devices

You enable discovery of a scene in the same way you enable discovery of a device. However, you must only enable the discovery of scenes with devices that do not represent a security or safety risk to the customer. This means that if a scene contains disallowed devices, it should not be included in a discovery response.

Following are examples of allowed and disallowed devices.

Allowed devices

The following device types are allowed to be incorporated as part of a scene:

  • Fans
  • Light bulbs
  • Speakers
  • Switched electrical outlets
  • Thermostats
  • Window blinds

Devices that are not allowed

Device types that have security or safety considerations are prohibited. The following list contains examples of devices that are not allowed. If we determine that your smart home skill allows the discovery of scenes that affect disallowed devices, it will not pass the certification process.

  • Cameras
  • Cooking appliances
  • Door locks
  • Garage doors
  • Security sensors
  • Security systems

In addition, your skill should return an error if a customer adds a disallowed device to a discovered scene, and then tries to interact with that scene. For example, if a customer adds a door lock to their bedtime scene, and then asks Alexa to turn that scene on, your skill adapter should return an error.

DiscoveryResponse requirements to describe a scene

Alexa sends a discovery request and you describes a scene as an endpoint, just how you would describe a device in the [Discover.Response][alexa-discovery#discoverresponse] event. However, there are special requirements for some of the response properties when you describe a scene.

  • The displayCategories array should include either SCENE_TRIGGER or "ACTIVITY_TRIGGER to indicate the endpoint is a scene

  • The description must be present and include the word "scene" as well as how the scene is connected. For example: "scene connected via vendor name". The friendly description should not exceed 128 characters.

  • A friendlyName is the name that customers use to interact with your scene and must be present. The goal is to enable customers to interact with a scene in a way that is natural and easy. A friendlyName should follow these guidelines:

    • Preferred option includes only the scene name. This provides the simplest and most natural way for a customer to interact with a scene
    • Optionally includes the room name, if a similar scene is offered in different rooms
    • Optionally includes "scene"
    • Optionally includes the preposition "in" between the scene name and a room name
    • Should not include special characters or punctuation
    • Should not exceed 128 characters

The following table lists some example friendly names and the utterance a customer would use to turn on that scene.

Friendly Name Format Friendly Name Example Customer utterance
scene namebedtime"Alexa, turn on bedtime"
scene name + scenebedtime scene"Alexa, turn on bedtime scene"
scene name + in + room namebedtime in nursery"Alexa, turn on bedtime in nursery"
  • The capabilities array must contain the SceneController capability.
  • Support for activation is required and implied when you specify the interface support
  • Supports for deactivation is specified with the supportsDeactivation field. This should be true if you handle the deactivation directive.

Discover.Response with scenes

A Discover.Response event returns all of the devices or scenes associated with the customer's device cloud account and is the expected response for a Discover directive. For more information about response properties, see Discover.Response.

The following code shows a Discovery.Response from a skill that includes scenes.

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "uniqueIdOfScene",
          "manufacturerName": "the manufacturer name of the endpoint",
          "friendlyName": "Watch TV",
          "description": "a TV scene connected via MyVendor",
          "displayCategories": [ "ACTIVITY_TRIGGER" ],
          "cookie": {
          },
          "capabilities":
          [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
             "version" : "3",
              "supportsDeactivation" : false,
              "proactivelyReported" : true
            }
          ]
        }
      ]
    }
  }
}

Scene discovery limit

Once discovered, every device and scene that your skill provides in the discovery process displays to the customer in the Alexa app. To keep a customer-friendly experience, you should not describe more than 12 default scenes in your Discover.Response. A customer can configure as many custom scenes as they want.

Activate request for scenes

A scene must support activation, which means that your skill must handle the Activate directive, and respond with a ActivationStarted event or an error message if the request could not be completed.

Example Utterance:

"Alexa, activate watch tv"

Activate example for a scene:

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Activate",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "uniqueIdOfScene"
    },
    "payload": {
    }
  }
}

ActivationStarted example

{
  "context" : { },
  "event": {
    "header": {
      "messageId": "8d9c4fa2-9de0-4e75-ac38-9dde79abb1bd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa.SceneController",
      "name": "ActivationStarted",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "cause" : {
        "type" : "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T23:23:23.23Z"
    }
  }
}

Additional Documentation

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment