Alexa.ToggleController Interface

The ToggleController interface enables your skill to model individual components of an endpoint that can be turned on or off. You can include multiple instances of a ToggleController on a single endpoint, as long as they have unique values in the instance and friendlyNames fields.

To control the overall power state of a device, use PowerController.

Discovery response

The following example shows a discovery response (Discover.Response) for a smart home skill that implements the ToggleController interface.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "AddOrUpdateReport",
      "payloadVersion": "3",
      "messageId": "00000000-0000-0000-0000-000000000000"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "Tower Fan",
          "description": "Tower Fan by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "version": "3",
              "instance": "SampleManufacturer.Fan.Oscillate",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.Oscillate"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Rotate",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "proactivelyReported": true,
                "retrievable": true,
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Discovery response fields

The following table describes the fields that are specific to the discovery response for devices that implement the ToggleController interface. All fields are required.

Field Description Type
instance A unique identifier for this instance of the ToggleController interface. string that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ &
capabilityResources A capabilityResources object specifying the names that customers can use for VUI and GUI interactions. object

CapabilityResources objects

For more information on capabilityResources objects, see Resources and Assets.

Directives

The ToggleController interface supports directives to turn a component on or off, and to query the state of the component. The following example is a query utterance:

User: Alexa, is oscillate on for the tower fan?

TurnOn

The following are example utterances that result in a TurnOn directive.

User: Alexa, turn on oscillate on the tower fan.

The following example shows a TurnOn directive. There are no required or optional fields in the payload of a TurnOn directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "example instance ID",
      "name": "TurnOn",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOff

The following are example utterances that result in a TurnOff directive.

User: Alexa, turn off oscillate on the tower fan.

The following example shows a TurnOff directive. There are no required or optional fields in the payload of a TurnOff directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "example instance ID",
      "name": "TurnOff",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Properties and events

For this interface, you must reply in one of the following ways:

  • Synchronously, which means you send a Response event to Alexa in response to a TurnOn or TurnOff directive. You send this response from the Lambda function.
  • Asynchronously, which means you send a Response event to the Alexa event gateway. When you respond asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive that you are responding to.

When you send a Response, you should include the state of the interface properties in the context of the message.

Properties

When the state of a toggle changes, send a state report with a toggleState property. You must also include the instance to specify which ToggleController of the device you are reporting state for.

Property name Type Description
toggleState ToggleState Indicates the whether the toggle is on or off. Valid values are ON and OFF.

Response

Send a Response event when a TurnOn or TurnOff request completes successfully.

Example Response for a TurnOn request

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ToggleController",
        "name": "toggleState",
        "instance": "example instance ID",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Example Response for a TurnOff request

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ToggleController",
        "instance": "example instance ID",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should respond with an error when you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more information.