Alexa.ToggleController Interface 3

Implement the Alexa.ToggleController interface in your Alexa add-on 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 add-on. The following examples show some user utterances:

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

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 , , , and 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 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 add-on 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 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 add-on.

TurnOn directive

Support the TurnOn directive so that users can turn on features of devices. The following examples show user utterances:

TurnOn directive example

The following example shows a TurnOn directive that Alexa sends to your add-on.

{
  "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. A successful response confirms that the endpoint completed the requested action. You can respond synchronously from your Lambda function or asynchronously through the Alexa event gateway. If you choose to respond asynchronously, include a correlation token and a scope with an authorization token. For details about both response types, see Alexa.Response. 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": "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:

TurnOff directive example

The following example shows a TurnOff directive that Alexa sends to your add-on.

{
  "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. A successful response confirms that the endpoint completed the requested action. You can respond synchronously from your Lambda function or asynchronously through the Alexa event gateway. If you choose to respond asynchronously, include a correlation token and a scope with an authorization token. For details about both response types, see Alexa.Response. 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,

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
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Semantics

Use semantics to enable additional utterances

Use semantics to enable Alexa hunches

Discovery

Capabilities array

Discovery response examples

Oven example

Semantics example

Range and toggle controllers example

Directives

TurnOn directive

TurnOn directive example

TurnOn directive payload

TurnOn response

TurnOn directive error handling

TurnOff directive

TurnOff directive example

TurnOff directive payload

TurnOff response

TurnOff directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Reportable properties

​Semantics

​Use semantics to enable additional utterances

​Use semantics to enable Alexa hunches

​Discovery

​Capabilities array

​Discovery response examples

​Oven example

​Semantics example

​Range and toggle controllers example

​Directives

​TurnOn directive

​TurnOn directive example

​TurnOn directive payload

​TurnOn response

​TurnOn directive error handling

​TurnOff directive

​TurnOff directive example

​TurnOff directive payload

​TurnOff response

​TurnOff directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Reportable properties

Semantics

Use semantics to enable additional utterances

Use semantics to enable Alexa hunches

Discovery

Capabilities array

Discovery response examples

Oven example

Semantics example

Range and toggle controllers example

Directives

TurnOn directive

TurnOn directive example

TurnOn directive payload

TurnOn response

TurnOn directive error handling

TurnOff directive

TurnOff directive example

TurnOff directive payload

TurnOff response

TurnOff directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics