Alexa.ToggleController Interface 3
Implement the Alexa.ToggleController interface in your Alexa skill so that users can control toggle settings of devices. You can use the Alexa.ToggleController interface to model properties of a device that you can set to on or off, such as the oscillation feature of a fan, or an oven light. The Alexa.ToggleController interface is a generic controller interface.
The Alexa.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 languages that the Alexa.ToggleController interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
The Alexa.ToggleController interface uses the pre-built voice interaction model. After the user says one of the following utterances, Alexa sends a corresponding directive to your skill.
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?
Alexa, turn on guest Wi-Fi.
Alexa, turn on guest network.
Alexa, turn off guest Wi-Fi.
Alexa, turn off guest network.
Alexa, is the guest Wi-Fi on?
Alexa, is the guest network on?
Alexa, schalte die Eismaschine ein.
Alexa, schalte den Eco-Modus aus.
Alexa, ist Oszillieren auf dem Turmventilator an?
Alexa, schalte Gast-WLAN ein.
Alexa, schalte das Gastnetzwerk ein.
Alexa, schalte das Gast-WLAN aus.
Alexa, schalte das Gastnetzwerk aus.
Alexa, ist das Gast-WLAN an?
Alexa, ist das Gastnetzwerk an?
Alexa, allume la machine à glaçons.
Alexa, désactive le mode économique.
Alexa, est-ce que l'oscillation est activée pour le ventilateur?
Alexa, allume le Wi-Fi invité.
Alexa, allume le réseau invité.
Alexa, éteins le Wi-Fi invité.
Alexa, éteins le réseau invité.
Alexa, est-ce que le Wi-Fi invité est allumé?
Alexa, est-ce que le réseau invité est allumé?
Alexa, आइस मेकर चालू करें।
Alexa, ईको मोड बंद करें।
Alexa, टावर फैन के लिए दोलन कर रही है?
Alexa, अतिथि Wifi चालू करें
Alexa, अतिथि Network चालू करें
Alexa, अतिथि Wifi बंद करें
Alexa, अतिथि नेटवर्क बंद करें
Alexa, क्या अतिथि Wifi चालू है?
Alexa, क्या अतिथि Network चालू है?
Alexa, accendi la macchina del ghiaccio.
Alexa, disattiva la modalità eco.
Alexa, è attiva l'oscillazione per il ventilatore?
Alexa, attiva WiFi Ospite.
Alexa, attiva Rete Ospite.
Alexa, disattiva WiFi Ospite.
Alexa, disattiva Rete Ospite.
Alexa, è attivo il WiFi Ospite?
Alexa, è attiva la Rete Ospite?
アレクサ、コーヒーメーカーをつけて
アレクサ、エコモードを消して
アレクサ、扇風機の首振りはついている？
アレクサ、ゲストWiFiをつけて
アレクサ、ゲストネットワークをオンにして
アレクサ、ゲストWiFiを消して
アレクサ、ゲストネットワークをオフにして
アレクサ、ゲストWiFiはオンになってる?
アレクサ、ゲストネットワークはついている?
Alexa, ligue a máquina de gelo.
Alexa, desligue o modo ecológico.
Alexa, a oscilação está ativada no ventilador de torre?
Alexa, ligue Wi-Fi para convidados.
Alexa, ligue Rede de convidados.
Alexa, desligue Wi-Fi para convidados.
Alexa, desligue Rede de convidados.
Alexa, o Wi-Fi para convidados está ligado?
Alexa, o Rede de convidados está ligado?
Alexa, enciende la máquina de hielo.
Alexa, desactiva el modo ecológico.
Alexa, ¿está activada la oscilación del ventilador?
Alexa, enciende el Wifi de invitados.
Alexa, enciende la Red de invitados.
Alexa, apaga el Wifi de invitados.
Alexa, apaga la Red de invitados.
Alexa, ¿está encendido el Wifi de invitados?
Alexa, ¿está encendida la Red de invitados?
Alexa, zet de ijsmachine aan.
Alexa, eco modus uitschakelen.
Alexa, staat oscilleren aan voor de torenventilator?
Alexa, zet WiFi op het Gastnetwerk aan.
Alexa, zet het Gastnetwerk aan.
Alexa, zet WiFi op het Gastnetwerk uit.
Alexa, zet het Gastnetwerk uit.
Alexa, staat WiFi op het Gastnetwerk aan?
Alexa, staat het Gastnetwerk aan?
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 den Mülleimer.
Alexa, schließe den Mülleimer.
Alexa, ouvre le couvercle de la poubelle.
Alexa, ferme le couvercle de la poubelle.
Alexa, कचरे के डिब्बे का ढक्कन खोलो।
Alexa, कचरे के डिब्बे का ढक्कन बंद करो।
Alexa, apri il coperchio del bidone.
Alexa, chiudi il coperchio del bidone.
アレクサ、ゴミ箱のフタを開いて
アレクサ、ゴミ箱のフタを閉じて
Alexa, abra a tampa da lixeira.
Alexa, feche a tampa da lixeira.
Alexa, abre el bote.
Alexa, cierra el bote de basura.
Alexa, doe de prullenbak open.
Alexa, doe de prullenbak dicht.
Reportable properties
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. This attribute defines the name of the toggle. You identify your instance names in your discovery response.
The following example shows a toggle for an oven light.
{
"namespace": "Alexa.ToggleController",
"instance": "Oven.OvenLight",
"name": "toggleState",
"value": "ON"
}
Semantics
Use semantics to enable additional features, such as additional user utterances and Alexa hunches for your device. To use semantics, include a semantics object in your discover response as described in the Discovery section.
Use semantics to enable additional utterances
When you use the Alexa.ToggleController interface, Alexa provides the voice interaction model for you. Users can interact with your device by saying the standard Alexa.ToggleController utterances. For details, see utterances.
You can enable additional utterances by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to the Alexa.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.
Alexa.ToggleController instance, you can't map the phrase "open" on any other Alexa.ToggleController instances, any Alexa.ModeController instances, or any Alexa.RangeController instances for the endpoint. You can use the same semantic phrase "open" across multiple endpoints that you report.
Use semantics to enable Alexa hunches
You can use semantics to enable Alexa hunches for your device to conserve energy on behalf of users. For details, see Semantics for Alexa hunches.
Discovery
You describe endpoints that support Alexa.ToggleController by 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.
For connected vehicles that use Alexa user identification, include directiveConfigurations in your discovery response to configure the authentication confidence level and policy name. For details, see directiveConfigurations.
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 Alexa.ToggleController entry in the capabilities array, you can optionally include a semantics object. For details, see using semantics to enable additional utterances.
For the full list of display categories, see display categories.
To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.
Capabilities array
In addition to the usual discovery response fields, for each Alexa.ToggleController entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
Name of the toggle, for example Fan.Light or Fan.Oscillate. |
String |
capabilityResources |
Friendly names that users can use to interact with the toggle. | CapabilityResources object |
Discovery response examples
Oven example
The following example shows a Discover.Response message for an oven that supports the Alexa.ToggleController interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Kitchen Appliance Plus",
"description": "Smart Oven by Kitchen Appliance Plus",
"friendlyName": "Oven",
"displayCategories": ["OVEN"],
"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": "text",
"value": {
"text": "Luz del horno",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Lumière du four",
"locale": "fr-CA"
}
}
]
}
},
{
"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": "text",
"value": {
"text": "Todavía está caliente",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Encore chaude",
"locale": "fr-CA"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Semantics example
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": "Unique identifier, preferably a version 4 UUID"
},
"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"
}
},
{
"@type": "text",
"value": {
"text": "Tapa del bote de basura",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Couvercle de poubelle",
"locale": "fr-CA"
}
}
]
},
"semantics": {
"actionMappings": [
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Close"],
"directive": {
"name": "TurnOff",
"payload": {}
}
},
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Open"],
"directive": {
"name": "TurnOn",
"payload": {}
}
}
],
"stateMappings": [
{
"@type": "StatesToValue",
"states": ["Alexa.States.Closed"],
"value": "OFF"
},
{
"@type": "StatesToValue",
"states": ["Alexa.States.Open"],
"value": "ON"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Range and toggle controllers example
The following example shows a Discover.Response message for a fan that supports the Alexa.PowerController interface and both the Alexa.RangeController and Alexa.ToggleController interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"friendlyName": "Tower Fan",
"description": "Tower Fan by Sample Manufacturer",
"manufacturerName": "Sample Manufacturer",
"displayCategories": ["FAN"],
"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"
}
},
{
"@type": "text",
"value": {
"text": "Rotation",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Girar",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Rotation",
"locale": "fr-CA"
}
}
]
},
"properties": {
"proactivelyReported": true,
"retrievable": true,
"supported": [
{
"name": "toggleState"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.RangeController",
"version": "3",
"instance": "SampleManufacturer.Fan.Speed",
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Setting.FanSpeed"
}
},
{
"@type": "text",
"value": {
"text": "Speed",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Velocidad",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Vitesse",
"locale": "fr-CA"
}
}
]
},
"properties": {
"supported": [
{
"name": "rangeValue"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedRange": {
"minimumValue": 1,
"maximumValue": 10,
"precision": 1
},
"presets": [
{
"rangeValue": 10,
"presetResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Maximum"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.High"
}
},
{
"@type": "text",
"value": {
"text": "Highest",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Fast",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Alta",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Élevée",
"locale": "fr-CA"
}
}
]
}
},
{
"rangeValue": 1,
"presetResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Minimum"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Low"
}
},
{
"@type": "text",
"value": {
"text": "Lowest",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Slow",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Baja",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Faible",
"locale": "fr-CA"
}
}
]
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
Alexa sends the following Alexa.ToggleController interface directives to your skill.
TurnOn directive
Support the TurnOn directive so that users can turn on features of devices.
The following examples show user utterances:
Alexa, turn on light on the oven.
Alexa, schalte das Licht in dem Ofen ein.
Alexa, allume la lumière du four.
Alexa, ओवन पर लाइट चालू करें।
Alexa, accendi la luce del forno.
アレクサ、オーブンの電気をつけて
Alexa, acenda a luz do forno.
Alexa, enciende la luz del horno.
Alexa, zet het licht van de oven aan.
TurnOn directive example
The following example shows a TurnOn directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ToggleController",
"instance": "Oven.Light",
"name": "TurnOn",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {}
}
}
TurnOn directive payload
The TurnOn directive doesn't define a payload.
TurnOn response
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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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 examples show user utterances:
Alexa, turn off light on the oven.
Alexa, schalte das Licht in dem Ofen aus.
Alexa, éteins la lumière du four.
Alexa, ओवन की लाइट बंद कर दो।
Alexa, spegni la luce del forno.
アレクサ、オーブンの電気を消して
Alexa, apague a luz do forno.
Alexa, apaga la luz del horno.
Alexa, zet het licht van de oven uit.
TurnOff directive example
The following example shows a TurnOff directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ToggleController",
"instance": "Oven.Light",
"name": "TurnOff",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {}
}
}
TurnOff directive payload
The TurnOff directive doesn't define a payload.
TurnOff response
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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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 the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
Support the ReportState directive so that users can ask whether features of their devices are on or off. The following example shows the StateReport response to the user utterance, "Alexa, is residual heat on for the oven?"
StateReport response example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 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-04T08:00:00.10Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
Change reporting
You send a ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ToggleController",
"instance": "Oven.OvenLight",
"name": "toggleState",
"value": "OFF",
"timeOfSample": "2017-02-04T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ToggleController",
"instance": "Stovetop.ResidualHeat",
"name": "toggleState",
"value": "ON",
"timeOfSample": "2017-02-04T16:20:50.42Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
},
"context": {
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-04T16:00:00.00Z",
"uncertaintyInMilliseconds": 0
}
}
Related topics
Last updated: Aug 23, 2024