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

{
  "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

{
  "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:

SceneController