Alexa.SceneController Interface

The SceneController interface describes messages for activating and optionally deactivating endpoints. It’s important to note that activation support is implied when an endpoint implements this interface, but you describe whether an endpoint can be deactivated during device discovery.

Discovery

When you describe an endpoint as supporting the Alexa.SceneController capability interface during discovery, support for activation is implied, because it is required. However, you must indicate whether an endpoint supports deactivation with the supportsDeactivation field.

DiscoveryResponse example containing Alexa.SceneController

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "uniqueIdOfScene",
          "manufacturerName": "the manufacturer name of the endpoint",
          "friendlyName": "Watch TV",
          "description": "a description that is shown to the customer",
          "displayCategories": [ "ACTIVITY_TRIGGER" ],
          "cookie": {
          },
          "capabilities":
          [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version" : "3",
              "supportsDeactivation" : false,
              "proactivelyReported" : true
            }
          ]
        }
      ]
    }
  }
}

Directives

SceneController has two directives; Activation and Deactivation. A scene must support activation, but deactivation is optional. If deactivation is supported, you should indicate this during discovery of the scene. See Discovery for more details.

Activation

A message to activate a scene.

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Activate",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Deactivate

A message to deactivate a scene. It’s optional for an endpoint to support deactivation.

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Deactivate",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Properties and Events

You can send events synchronously or asynchronously for a scene controller. When you respond asynchronously you should include a token to authenticate the customer and a correlation token to identify the message exchange.

Reportable Properties

Property Name Description Type
None The Alexa.SceneController interface does not define any reportable properties.  

ActivationStarted Event

Send an ActivationStarted event as a synchronous response to an endpoint activation request or proactively when the activation occurs for another reason. For example, send this event when someone asks Alexa to activate the endpoint, or when someone triggers an activation in another application. You indicate the cause of the activation in the message payload. Note that if you are responding asynchronously to a directive, this event should include a correlation token; otherwise it is not required.

ActivationStarted example

{
  "context" : { },
  "event": {
    "header": {
      "messageId": "8d9c4fa2-9de0-4e75-ac38-9dde79abb1bd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa.SceneController",
      "name": "ActivationStarted",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "cause" : {
        "type" : "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T23:23:23.23Z"
    }
  }
}

Payload details

Field Description Type Required
cause Describes why this event occurred. Cause object Yes
timestamp When the activation event occurred. string containing a time in ISO 8601 format. Should be specified in UTC. Yes

DeactivationStarted

Send an DeactivationStarted event as a synchronous response to an endpoint deactivation request or asynchronously when the deactivation occurs for another reason. For example, send this event when someone asks Alexa to deactivate the endpoint, or when someone triggers an deactivation in another application. You indicate the cause of the activation in the message payload. Note that if you are responding synchronously to a directive, this event should include a correlation token; otherwise, it is not required.

DeactivationStarted example

{
  "context" : { },
  "event": {
    "header": {
      "messageId": "8d9c4fa2-9de0-4e75-ac38-9dde79abb1bd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa.SceneController",
      "name": "DeactivationStarted",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "cause" : {
        "type" : "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T23:23:23.23Z"
    }
  }
}
Field Description Type Required
cause Describes why this event occurred. Cause object Yes
timestamp When the activation event occurred. string containing a time in ISO 8601 format. Should be specified in UTC. Yes

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

SceneController