Alexa.SceneController Interface 3

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 Smart Home Skills.

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.

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.

For the list of languages that the Alexa.SceneController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

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

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.

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, your skill won't pass certification.

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

  • Fans
  • Light bulbs
  • Speakers
  • Switched electrical outlets
  • Thermostats
  • TVs
  • 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.

Reportable properties

The Alexa.SceneController interface doesn't define any reportable properties.

Discovery

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

In your discovery response, you must configure the endpoint information for an endpoint that supports Alexa.SceneController as follows:

  • Use the endpointId to identify a scene and not a physical device.
  • In the description field, include the word "scene" and describe how the scene connects. For example, "Party scene connected by vendor name."
  • Include the friendlyName field. The user interacts with your scene by using the friendly name. Follow these guidelines to define the friendlyName field:
    • Include only the scene name. This name 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.
  • Set displayCategories to ACTIVITY_TRIGGER or SCENE_TRIGGER. For the full list of display categories, see display categories.

In addition to the usual discovery response fields, for Alexa.SceneController, include the 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": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the scene",
                "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 and events

Alexa.SceneController interface defines the following directives and events.

Activate directive

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

The following examples show user utterances:

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

Activate directive example

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

{
    "directive": {
        "header": {
            "namespace": "Alexa.SceneController",
            "name": "Activate",
            "messageId": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {}
    }
}

Activate directive payload

The Activate directive doesn't define any payload parameters. Include an empty payload object.

Activate response

If you handle an Activate directive successfully, respond with an ActivationStarted event. In the context object, include all reportable properties of the endpoint. Also, include the correlationToken set to the value from the directive request.

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

ActivationStarted event example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.SceneController",
            "name": "ActivationStarted",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "cause": {
                "type": "VOICE_INTERACTION"
            },
            "timestamp": "2017-02-03T16:20:50Z"
        }
    },
    "context": {}
}

ActivationStarted event payload

The following table shows the payload details for the ActivationStarted response.

Property Description Type Required

cause

Indicates how the request to activate the scene was made.
Valid value: VOICE_INTERACTION.

Cause object.

Yes

timestamp

Time the activation starts.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

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:

Alexa, turn off Living Room Party.

Deactivate directive example

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

{
    "directive": {
        "header": {
            "namespace": "Alexa.SceneController",
            "name": "Deactivate",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {}
    }
}

Deactivate response

If you handle a Deactivate directive successfully, respond with a DeactivationStarted event. In the context object, include all reportable properties of the endpoint. Also, include the correlationToken set to the value from the directive request.

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

DeactivationStarted event example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.SceneController",
            "name": "DeactivationStarted",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "cause": {
                "type": "VOICE_INTERACTION"
            },
            "timestamp": "2017-02-03T16:20:50Z"
        }
    },
    "context": {}
}

DeactivationStarted response payload

The following table shows the payload details for the DeactivationStarted response.

Property Description Type Required

cause

Indicates how the request to deactivate the scene was made.
Valid value: VOICE_INTERACTION.

Cause object.

Yes

timestamp

Time the activation starts.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

Deactivate directive error handling

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

Change reporting

You send an Alexa.ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response.

The Alexa.SceneController interface doesn't define any proactively reportable properties. However, you send change reports for the other interfaces that you implement in your skill. For details about change reports, see Understand State and Change Reporting.