Alexa.SceneController Interface
The Alexa.SceneController interface describes messages for activating and optionally deactivating multiple devices that are grouped together into a scene. Activation support is required, but you describe whether a scene can be deactivated during device discovery.
For the list of locales that are supported for the SceneController interface, see List of Capability Interfaces and Supported Locales.
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, start my day.
Alexa, 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.
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
{
"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. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token; otherwise it is not required.
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
{
"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. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token; otherwise it is not required.
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:
