感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

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. You can also use the ToggleController interface to model properties of an endpoint that users can't change.

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:

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 user utterances:

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

You can optionally enable additional utterances by using semantics. The following examples show some additional user utterances:

Alexa, open the garbage can lid.
Alexa, close the garbage can lid.

Alexa, öffne der Deckel der Mülltonne.
Alexa, schließe der Deckel der Mülltonne.

After the user 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"
}

Using semantics to enable additional utterances

When you use the Alexa.ToggleController interface, the voice interaction model is already built for you. Users can interact with your device by saying the standard ToggleController utterances. For more information, see utterances.

You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to the ToggleController directives TurnOn and TurnOff. For example, if you have a controller for a garbage can lid, you can map the phrases "open" to the TurnOn directive.

To use semantics, include a semantics object in your discover response as described in the following section.

Discovery

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

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

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

For each ToggleController entry in the capabilities array, you can optionally include a semantics object. For more information, see using semantics to enable additional utterances.

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 users can use to interact with the toggle. A CapabilityResources object.

Discover response examples

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": "Stovetop.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"
            }
          ]
        }
      ]
    }
  }
}

Discover response example with semantics

The following example shows a Discover.Response message for an automated garbage can lid that supports the Alexa.ToggleController interface and uses semantics.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<manufacturer name>",
          "description": "<Smart Garbage Can by Manufacturer>",
          "friendlyName": "<garbage can>",
          "displayCategories": ["OTHER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "GarbageCan.Lid",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "garbage can lid",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "semantics": {
                "actionMappings": [
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Close"],
                    "directive": {
                      "name": "TurnOff",
                      "payload": {}
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Open"],
                    "directive": {
                      "name": "TurnOn",
                      "payload": {}
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

TurnOn directive

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

The following example shows a user 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. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.

TurnOff directive

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

The following example shows a user 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. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.

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 users can ask whether features of their devices are on or off.

The following examples show some user utterances:

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": "Stovetop.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": "Stovetop.ResidualHeat",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {}
}