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, schalte die Eismaschine ein.
Alexa, schalte den Eco-Modus aus.
Alexa, ist Oszillieren auf dem Turmventilator 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, आइस मेकर चालू करें।
Alexa, ईको मोड बंद करें।
Alexa, टावर फैन के लिए दोलन कर रही है?

Alexa, accendi la macchina del ghiaccio.
Alexa, disattiva la modalità eco.
Alexa, è attiva l'oscillazione per il ventilatore?

アレクサ、コーヒーメーカーをつけて
アレクサ、エコモードを消して
アレクサ、扇風機の首振りはついている?

Alexa, ligue a máquina de gelo.
Alexa, desligue o modo ecológico.
Alexa, a oscilação está ativada no ventilador de torre?

Alexa, enciende la máquina de hielo.
Alexa, desactiva el modo ecológico.
Alexa, ¿está activada la oscilación del ventilador?

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.

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.

Copied to clipboard.

{
  "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.

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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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.

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.

Copied to clipboard.

{
  "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.

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.

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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-03T16:20:50.52Z",
        "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

Copied to clipboard.

{
  "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": "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": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50.52Z",
    "uncertaintyInMilliseconds": 0
  }
}

Was this page helpful?

Last updated: Jan 26, 2024