Alexa.ToggleController Interface
The ToggleController interface enables your skill to model individual components of an endpoint that can be turned on or off. You can include multiple instances of a ToggleController on a single endpoint, as long as they have unique values in the instance and friendlyNames fields.
To control the overall power state of a device, use PowerController.
Discovery response
The following example shows a discovery response (Discover.Response) for a smart home skill that implements the ToggleController interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "00000000-0000-0000-0000-000000000000"
},
"payload": {
"endpoints": [
{
"endpointId": "appliance-001",
"friendlyName": "Tower Fan",
"description": "Tower Fan by Sample Manufacturer",
"manufacturerName": "Sample Manufacturer",
"displayCategories": [
"OTHER"
],
"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"
}
}
]
},
"properties": {
"proactivelyReported": true,
"retrievable": true,
"supported": [
{
"name": "toggleState"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Discovery response fields
The following table describes the fields that are specific to the discovery response for devices that implement the ToggleController interface. All fields are required.
| Field | Description | Type |
|---|---|---|
instance |
A unique identifier for this instance of the ToggleController interface. |
string that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ & |
capabilityResources |
A capabilityResources object specifying the names that customers can use for VUI and GUI interactions. |
object |
CapabilityResources objects
For more information on capabilityResources objects, see Resources and Assets.
Directives
The ToggleController interface supports directives to turn a component on or off, and to query the state of the component. The following example is a query utterance:
User: Alexa, is oscillate on for the tower fan?
TurnOn
The following are example utterances that result in a TurnOn directive.
User: Alexa, turn on oscillate on the tower fan.
The following example shows a TurnOn directive. There are no required or optional fields in the payload of a TurnOn directive.
{
"directive": {
"header": {
"namespace": "Alexa.ToggleController",
"instance": "example instance ID",
"name": "TurnOn",
"payloadVersion": "3",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {}
}
}
TurnOff
The following are example utterances that result in a TurnOff directive.
User: Alexa, turn off oscillate on the tower fan.
The following example shows a TurnOff directive. There are no required or optional fields in the payload of a TurnOff directive.
{
"directive": {
"header": {
"namespace": "Alexa.ToggleController",
"instance": "example instance ID",
"name": "TurnOff",
"payloadVersion": "3",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {}
}
}
Properties and events
For this interface, you must reply in one of the following ways:
- Synchronously, which means you send a
Responseevent to Alexa in response to aTurnOnorTurnOffdirective. You send this response from the Lambda function. - Asynchronously, which means you send a
Responseevent to the Alexa event gateway. When you respond asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive that you are responding to.
When you send a Response, you should include the state of the interface properties in the context of the message.
Properties
When the state of a toggle changes, send a state report with a toggleState property. You must also include the instance to specify which ToggleController of the device you are reporting state for.
| Property name | Type | Description |
|---|---|---|
toggleState |
ToggleState | Indicates the whether the toggle is on or off. Valid values are ON and OFF. |
Response
Send a Response event when a TurnOn or TurnOff request completes successfully.
Example Response for a TurnOn request
{
"context": {
"properties": [
{
"namespace": "Alexa.ToggleController",
"name": "toggleState",
"instance": "example instance ID",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
},
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {}
}
}
Example Response for a TurnOff request
{
"context": {
"properties": [
{
"namespace": "Alexa.ToggleController",
"instance": "example instance ID",
"name": "toggleState",
"value": "OFF",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
},
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {}
}
}
ErrorResponse
You should respond with an error when you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more information.