Gracias por tu visita. Esta página solo está disponible en inglés.

Alexa.ToggleController Interface

The Alexa.ToggleController capability interface describes messages used to toggle settings of an endpoint. You can use the ToggleController interface to model properties of an endpoint that can be set to on or off, such as the oscillation feature of a fan, or an oven light.

The ToggleController interface is highly configurable and enables you to model many different kinds of settings for many different kinds of devices. Use one of the following more specific interfaces if it's appropriate for your device:

You can also use the ToggleController interface to model properties of an endpoint that customers can't change as described in the discovery section.

For the list of locales that are supported for the ToggleController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.ToggleController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, turn on the ice maker.
Alexa, turn off eco mode.
Alexa, is oscillate on for the tower fan?

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Properties and Objects

The toggleState property

The Alexa.ToggleController interface uses the toggleState property as the primary property. The valid values are ON or OFF.

An endpoint can support multiple toggle controllers, so you must always include the instance attribute for a toggleState property. You identify your instance names in your discovery response.

ToggleState property example

{
  "namespace": "Alexa.ToggleController",
  "instance": "Oven.OvenLight",
  "name": "toggleState",
  "value": "ON"
}

Discovery

You describe endpoints that support Alexa.ToggleController using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for all of the interfaces and properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for interfaces and properties that you proactively report to Alexa in a change report.

You can model properties of an endpoint that customers can't change by setting nonControllable to true. For example, if a stove has a safety feature that warns customers when the stovetop is too hot to touch, you can report that state without allowing the customer to change it.

For the full list of display categories, see display categories.

In addition to the usual discovery response fields, for each ToggleController entry in the capabilities array, include the following fields.

Field Description Type
instance The name of the toggle, for example Fan.Light or Fan.Oscillate. String
capabilityResources Friendly names that customers can use to interact with the toggle. A CapabilityResources object.

Discover response example

The following example shows a Discover.Response message for an oven endpoint that supports the Alexa.ToggleController interface.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "Kitchen Appliance Plus",
          "description": "Smart Oven by Kitchen Appliance Plus",
          "friendlyName": "Oven",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Oven.OvenLight",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": false
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Oven Light",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Oven.ResidualHeat",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Stovetop is still hot",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

TurnOn directive

Support the TurnOn directive so that customers can turn on features of devices.

The following example shows a customer utterance:

Alexa, turn on light on the oven.

TurnOn directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "Oven.Light",
      "name": "TurnOn",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOn response event

If you handle a TurnOn directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.

TurnOn response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOn directive error handling

If you can't handle a TurnOn directive successfully, respond with an Alexa.ErrorResponse event.

TurnOff directive

Support the TurnOff directive so that customers can turn off features of devices.

The following example shows a customer utterance:

Alexa, turn off light on the oven.

TurnOff directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "Oven.Light",
      "name": "TurnOff",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOff response event

If you handle a TurnOff directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.

TurnOff response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOff directive error handling

If you can't handle a TurnOff directive successfully, respond with an Alexa.ErrorResponse event.

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For more information about state reports, see Understand State Reporting.

Support the ReportState directive so that customers can ask whether features of their devices are on or off.

The following example shows a customer utterance:

Alexa, is residual heat on for the oven?

StateReport response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Oven.ResidualHeat",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For more information about change reports, see Understand State Reporting.

ChangeReport event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ToggleController",
            "instance": "Oven.OvenLight",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ToggleController",
            "instance": "Oven.ResidualHeat",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {}
}