Alexa.SceneController Interface

Implement the Alexa.SceneController interface in your Alexa skill so that users can activate or deactivate multiple smart home devices that are grouped together into a scene. For details about Smart Home skills, see Understand the Smart Home Skill API.

Scenes set a combination of devices to a specific state for each device. Classify your scenes according to how the state changes occur:

Activity trigger — The state changes must occur in a specific order. For example, for a scene named "Watch Netflix" you might power on the TV first, and then set the input to HDMI1.
Scene trigger — The state changes can occur in any order. For example, for a scene named "Bedtime" you might turn off the lights and lower the thermostat, in any order.

For the list of languages that the SceneController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.SceneController interface, the voice interaction model is already built for you. The following examples show some user utterances:

English (All)

Alexa, turn on Start My Day.
Alexa, turn on Living Room Party.
Alexa, turn on Movie Night.

After the user says one of these utterances, Alexa sends a corresponding directive to your skill.

Overview

With the scene feature, a user can use their voice to set multiple devices to previously configured settings. Typically a user edits and creates scenes with an Alexa-compatible hub or through a device manufacturer's app. You can also create an Alexa skill that provides scenes.

Supported and restricted device types

You can't create scenes that include device types that have security or safety considerations. If your smart home skill includes scenes with restricted device types, you skill won't pass certification.

Important: If a user of your skill adds a restricted device type to your scene, and then tries to interact with that scene, your skill must return an error. For example, if a user adds a door lock to your scene, and then asks Alexa to activate your scene, your skill should return an error.

You can support the following device types in your skill for a scene:

Fans
Light bulbs
Speakers
Switched electrical outlets
Thermostats
Window blinds

You can't support the following device types in your skill for a scene:

Cameras
Cooking appliances
Door locks
Garage doors
Security sensors
Security systems

Scene count limit

Every device and scene that your skill controls appears to the user in the Alexa app. For a user-friendly experience, don't include more than 12 default scenes in your skill. Users can configure as many custom scenes as they want.

Discovery

You describe endpoints that support Alexa.SceneController using the standard discovery mechanism described in Alexa.Discovery.

In your discover response, you must include the description field. The description must include the word "scene" and describe how the scene is connected. For example, "Party scene connected by vendor name". The description is limited to 128 characters.

In your discover response, you must include the friendlyName field. Your friendly name is how the user interacts with your scene and should follow these guidelines:

Include only the scene name. This provides the simplest and most natural way for a user to interact with a scene.
Optionally include the room name, if you offer a similar scene in a different room.
Optionally include the word "scene".
Optionally include the word "in" between the scene name and a room name.
Don't include special characters or punctuation.
Don't exceed 128 characters.

Use ACTIVITY_TRIGGER or SCENE_TRIGGER for the display category. For the full list of display categories, see display categories.

In addition to the usual discovery response fields, for SecurityPanelController, include a supportsDeactivation property to specify whether you support deactivating a scene.

Discover response example

The following example shows a Discover.Response message for a device that supports the Alexa.SceneController interface.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "Sample Vendor",
          "description": "Party scene by Sample Vendor",
          "friendlyName": "Living Room Party",
          "displayCategories": ["SCENE_TRIGGER"],
          "cookie": {},
          "capabilities": [
            {
                "type": "AlexaInterface",
                "interface": "Alexa.SceneController",
                "version": "3",
                "supportsDeactivation": false
            },
            {
                "type": "AlexaInterface",
                "interface": "Alexa",
                "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Activate directive

Support the Activate directive so that users can activate a scene. The Activate directive is required.

The following examples show user utterances:

English

Alexa, turn on the Library.
Alexa, turn on Movie Night.

Activate directive example

The following example illustrates an Activate directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Activate",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
    }
  }
}

Activate response event

If you handle an Activate directive successfully, respond with an ActivationStarted event. In the context object, include the values of all relevant properties.

You can send the ActivationStarted event synchronously or asynchronously. If you send the ActivationStarted asynchronously, include a correlation token and a scope with an authorization token. For details, see Response Events.

ActivationStarted event payload details

Field	Description	Type	Required
`cause`	How the request to activate the scene was made, such as by voice activation or by the Alexa app.	A Cause object.	Yes
`timestamp`	The time the activation starts, specified in UTC.	A string in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	Yes

ActivationStarted event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "ActivationStarted",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "cause" : {
        "type" : "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T16:20:50Z"
    }
  },
  "context": {
  }
}

Activate directive error handling

If you can't handle an Activate directive successfully, or if a user has added a restricted device type to your scene, respond with an Alexa.ErrorResponse event.

Deactivate directive

Support the Deactivate directive so that users can deactivate a scene. The Deactivate directive is optional.

The following examples show user utterances:

English

Alexa, turn off Living Room Party.

Deactivate directive example

The following example illustrates a Deactivate directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Deactivate",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
    }
  }
}

Deactivate response event

If you handle a Deactivate directive successfully, respond with a DeactivationStarted event.

DeactivationStarted event payload details

Field	Description	Type	Required
`cause`	How the request to deactivate the scene was made, such as by voice activation or by the Alexa app.	A Cause object.	Yes
`timestamp`	The time the deactivation starts, specified in UTC.	A string in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	Yes

DeactivationStarted event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "DeactivationStarted",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "cause": {
        "type": "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T16:20:50Z"
    }
  },
  "context": {
  }
}

Deactivate directive error handling

If you can't handle a Deactivate directive successfully, respond with an Alexa.ErrorResponse event.