Alexa.SceneController Interface

The 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.

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.

Discover response example

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"abc-123-def-456"
    },
    "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
            }
          ]
        }
      ]
    }
  }
}

Directives

The control and query directives in this interface are supported in skills that target the following languages:

  • English (CA)
  • English (IN)
  • English (UK)
  • English (US)
  • French (FR)
  • German
  • Italian
  • Spanish (ES)

See [Develop Smart Home Skills in Multiple Languages][develop-smart-home-skills-in-multiple-languages#decide-languages] for more information.

The SceneController interface has two directives; Activate and Deactivate. The Activate directive is required, but the Deactivate directive is optional. If you support Deactivate, indicate this during discovery of the scene. See Discovery for more details.

Activate directive

Use the Acivate directive to 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. There are no required or optional fields in the payload.

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 the Activate directive was handled 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:ss.sZ. 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

Use the Deacivate directive to 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. There are no required or optional fields in the payload.

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 the Deactivate directive was handled 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:ss.sZ. 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