Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

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:

SceneController