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 customer utterances:
Alexa, turn on Start My Day.
Alexa, turn on Living Room Party.
Alexa, turn on Movie Night.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery
You describe endpoints that support Alexa.SceneController using the standard discovery mechanism described in Alexa.Discovery.
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.
{
"event": {
"header": {
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload":{
"endpoints":[
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is shown in the Alexa app>",
"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 customers can activate a scene. The Activate directive is required.
The following examples show customer utterances:
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
{
"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, respond with an Alexa.ErrorResponse event.
Deactivate directive
Support the Deactivate directive so that customers can deactivate a scene. The Deactivate directive is optional.
The following examples show customer utterances:
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
{
"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.
