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

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 the display light feature of an alarm clock.

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 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": "Fan.Oscillate",
  "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.

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.

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

Discover response example

The following example shows a Discover.Response message for a fan that supports two instances of the Alexa.ToggleController interface, one for the light on the fan, and one for the oscillation feature of the fan.

{
  "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": "<device name, displayed in the Alexa app>",
          "displayCategories": ["FAN"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Fan.Light",
              "version": "3",
              "properties": {
                "proactivelyReported": true,
                "retrievable": true,
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ]
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Light",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Fan.Oscillate",
              "version": "3",
              "properties": {
                "proactivelyReported": true,
                "retrievable": true,
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ]
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Rotate",
                      "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 oscillate on the tower fan.

TurnOn directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "Fan.Oscillate",
      "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": "Fan.Oscillate",
        "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 oscillate on the tower fan.

TurnOff directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ToggleController",
      "instance": "Fan.Oscillate",
      "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": "Fan.Oscillate",
        "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 oscillate on for the tower fan?

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": "Fan.Oscillate",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Fan.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": "Fan.Oscillate",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ToggleController",
            "instance": "Fan.Light",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {}
}