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 more information about Smart Home skills, see Understand the Smart Home Skill API.
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 goodnight.
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. In addition, identify if deactivation is supported in the configuration of the Alexa.SceneController
capability. Support for activation is required, so you don't specify it during discovery. You describe whether a scene can be deactivated during device discovery by setting the supportsDeactivation
property.
Use SCENE_TRIGGER
or ACTIVITY_TRIGGER
for the display category. For the full list of display categories, see display categories.
Discover response example
{
"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": "Goodnight",
"displayCategories": ["SCENE_TRIGGER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.SceneController",
"version": "3",
"supportsDeactivation": false
}
]
},
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is shown in the Alexa app>",
"friendlyName": "Watch TV",
"displayCategories": ["ACTIVITY_TRIGGER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
},
{
"type": "AlexaInterface",
"interface": "Alexa.SceneController",
"version": "3",
"supportsDeactivation": true
}
]
}
]
}
}
}
Directives
Activate directive
Support the Activate
directive so that customers can activate a scene. The Activate
directive is required.
Sample customer utterances:
User: Alexa, turn on Library Lights
Activate directive payload details
The payload for the Activate
directive is empty.
Activate directive example
The following example illustrates an Activate
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.SceneController",
"name": "Activate",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001"
},
"payload": {
}
}
}
ActivationStarted event
If you handle an Activate
directive successfully, respond with an ActivationStarted
event.
ActivationStarted event payload details
Field | Description | Type | Required |
---|---|---|---|
cause |
The reason for the activation. | A Cause object. | Yes |
timestamp |
The time of the activation, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
ActivationStarted event example
{
"context" : { },
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa.SceneController",
"name": "ActivationStarted",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {
"cause" : {
"type" : "VOICE_INTERACTION"
},
"timestamp" : "2017-02-03T23:23:23.23Z"
}
}
}
Deactivate directive
Support the Deactivate
directive so that customers can deactivate a scene. The Deactivate
directive is optional.
Sample customer utterances:
User: Alexa, turn off Living Room Party
Deactivate directive payload details
The payload for the Deactivate
directive is empty.
Deactivate directive example
The following example illustrates a Deactivate
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.SceneController",
"name": "Deactivate",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001"
},
"payload": {
}
}
}
DeactivationStarted event
If you handle a Deactivate
directive successfully, respond with an DeactivationStarted
event.
DeactivationStarted event payload details
Field | Description | Type | Required |
---|---|---|---|
cause |
The reason for the deactivation. | A Cause object. | Yes |
timestamp |
The time of the deactivation, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
DeactivationStarted event example
{
"context" : { },
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa.SceneController",
"name": "DeactivationStarted",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {
"cause" : {
"type" : "VOICE_INTERACTION"
},
"timestamp" : "2017-02-03T23:23:23.23Z"
}
}
}
Error Handling
If an error occurs, respond with an ErrorResponse
event. For more information, see Alexa.ErrorResponse Interface.
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo: