Alexa.SceneController Interface 3

Implement the Alexa.SceneController interface in your Alexa add-on so that users can activate or deactivate multiple smart home devices grouped together into a scene. For more details about smart home add-ons, see Connect Your Device Cloud with Smart Home Add-ons. 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 add-on 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. After the user says one of these utterances, Alexa sends a corresponding directive to your add-on. The following examples show some user utterances:

Restricted device types

You can’t create scenes that include device types that have security or safety considerations. If your smart home add-on includes scenes with restricted device types, your add-on won’t pass certification. The following device types are restricted; don’t include them in a scene:

Cameras
Cooking appliances
Door locks
Garage doors
Security sensors
Security systems

Examples of device types that you can support in your add-on for a scene:

Fans
Light bulbs
Speakers
Switched electrical outlets
Thermostats
TVs
Window blinds

Scene count limit

Every device and scene that your add-on controls appears to the user in the Alexa app. For a user-friendly experience, don’t include more than 12 default scenes in your add-on. 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.

{
    "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:

Activate directive example

The following example shows an Activate directive that Alexa sends to your add-on.

{
    "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. The directive includes 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

{
    "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:

Deactivate directive example

The following example shows a Deactivate directive that Alexa sends to your add-on.

{
    "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

{
    "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 deactivation 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 add-on. For details about change reports, see Understand State and Change Reporting.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Restricted device types

Scene count limit

Reportable properties

Discovery

Discover response example

Directives and events

Activate directive

Activate directive example

Activate directive payload

Activate response

ActivationStarted event example

ActivationStarted event payload

Activate directive error handling

Deactivate directive

Deactivate directive example

Deactivate response

DeactivationStarted event example

DeactivationStarted response payload

Deactivate directive error handling

Change reporting

​Utterances

​Restricted device types

​Scene count limit

​Reportable properties

​Discovery

​Discover response example

​Directives and events

​Activate directive

​Activate directive example

​Activate directive payload

​Activate response

​ActivationStarted event example

​ActivationStarted event payload

​Activate directive error handling

​Deactivate directive

​Deactivate directive example

​Deactivate response

​DeactivationStarted event example

​DeactivationStarted response payload

​Deactivate directive error handling

​Change reporting

​Related topics

Utterances

Restricted device types

Scene count limit

Reportable properties

Discovery

Discover response example

Directives and events

Activate directive

Activate directive example

Activate directive payload

Activate response

ActivationStarted event example

ActivationStarted event payload

Activate directive error handling

Deactivate directive

Deactivate directive example

Deactivate response

DeactivationStarted event example

DeactivationStarted response payload

Deactivate directive error handling

Change reporting

Related topics