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.