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:
