Alexa.RangeController Interface 3

Implement the Alexa.RangeController interface in your Alexa add-on so that users can control the device settings represented by numbers within a minimum and maximum range. You can use the Alexa.RangeController interface to model properties of a device that the user can set to one of a range of values, such as the speed settings on a blender or a fan. The Alexa.RangeController interface is a generic controller interface. The Alexa.RangeController 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.RangeController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.RangeController 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:

Properties and objects

The Alexa.RangeController interface defines the following properties and objects.

RangeValue property

The Alexa.RangeController interface uses the rangeValue property as the primary property. The property values are numbers, and you specify the minimum value, maximum value, and precision in your discovery response. If you use the rangeValue property to represent a change, valid values include negative numbers. An endpoint can support multiple range controllers. To distinguish between range controllers, you must always include the instance attribute for a rangeValue property. You identify your instance names in your discovery response. The following example shows an instance of fan speed with a range.

{
  "namespace": "Alexa.RangeController",
  "instance": "Fan.Speed",
  "name": "rangeValue",
  "value": 10
}

Preset object

The Preset object represents a preset value for a range. Preset values must be divisible by precision. For example, for a range of 0–10 with precision of 5, the valid presets values are 0, 5, 10. The following example shows three Preset objects in a presets array. The presets represent low, medium, and high values for a range of 0–10.

"presets": [
  {
    "value": 0,
    "presetResources": {
    }
  },
  {
    "value": 5,
    "presetResources": {
    }
  },
  {
    "value": 10,
    "presetResources": {
    }
  }
]

Property	Description	Type	Required
`rangeValue`	Value in the range for the preset. Valid values: minimum range value + (n × `precision`) where n is an integer.	Integer	Yes
`presetResources`	Friendly names that users can use to interact with the preset value.	`PresetResources` object	Yes

PresetResources object

Use the PresetResources object to provide a set of friendly names that users can use to interact with preset values. The first friendly name is the name that appears in the Alexa app. For details, see Resources and Assets. The following example shows the preset resources for the high setting on a fan. Users can say phrases like

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

Semantics

Use semantics to enable additional features, such as additional user utterances and announcements when your device requires attention. 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.RangeController interface, the voice interaction model is already built for you. Users can interact with your device by saying the standard Alexa.RangeController utterances. For details, see utterances. You can optionally enable additional utterances by using semantics. When you use semantics, you manually map the phrases , , , and to the Alexa.RangeController directives SetRangeValue and AdjustRangeValue. For example, if you have a controller for a window shade, you can map the phrase to the AdjustRangeValue directive.

Use semantics to enable announcements

You can use semantics to enable announcements to the user when your device requires attention. Announcements take the form, Your <device friendly name>'s <instance friendly name> is <state>. For example, when the bin of their automatic vacuum cleaner is full, Alexa notifies the user with the following announcement: To enable announcements, implement the Alexa.ProactiveNotificationSource interface in your Alexa add-on. To indicate the states that you support, include a semantics object in your discovery response to map the rangeValue property to one of the Alexa.States values, such as Alexa.States.Full. You trigger announcements by sending an Alexa.ChangeReport to report a change in the device state. For more details about announcement text, see Alexa.ProactiveNotificationSource.

Discovery

You describe endpoints that support Alexa.RangeController 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. Set nonControllable to true for range controller properties that you want to report to the user, but don’t want the user to change. For each Alexa.RangeController entry in the capabilities array, you can optionally include a semantics object. For details, see use semantics to enable additional utterances and use semantics to enable announcements. 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.RangeController entry in the capabilities array, include the following fields.

Property	Description	Type	Required
`instance`	Name of the range. For example: `Fan.Speed`, `Camera.Pan`, `Camera.Tilt`, `Camera.Zoom`.	String	Yes
`capabilityResources`	Friendly names that users can use to interact with the range. If you enable announcements for the instance friendly name, include `@type` set to `text`.	CapabilityResources object	Yes
`configuration`	Defines the range and presets.	Object	Yes
`configuration.` `supportedRange`	Defines the range.	Object	Yes
`configuration.` `supportedRange.` `minimumValue`	Minimum value for the range.	Number	Yes
`configuration.` `supportedRange.` `maximumValue`	Maximum value for the range.	Number	Yes
`configuration.` `supportedRange.` `precision`	Amount by which the values change when moving through the range. This property also serves as the default when a user asks to change the value but doesn’t specify by how much. The `preset` values must be divisible by `precision`. For example, for a minimum range of 0 and a maximum range of 100 with `precision` of 5, valid presets values are 0, 5, 10, 15 … 95, 100.	Number	Yes
`configuration.` `unitOfMeasure`	Unit of measure for the range.	Units of measure string	No
`configuration.` `presets`	Named options that users can specify instead of numbers, such as “medium” or “maximum”.	Array of Preset objects	No

Discovery response examples

Fan example

The following example shows a Discover.Response message for a fan that supports the Alexa.RangeController and Alexa.PowerController interfaces.

Show/hide discovery response

{
  "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": "Fan manufacturer name",
          "description": "description that appears in the Alexa app",
          "friendlyName": "device name that appears in the Alexa app",
          "displayCategories": ["FAN"],
          "additionalAttributes": {
            "manufacturer" : "Fan manufacturer name",
            "model" : "Sample Model",
            "serialNumber": "the serial number",
            "customIdentifier": "your custom identifier"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "instance": "Fan.Speed",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": false
              },
              "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"
                    }
                  }
                ]
              },
              "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"
            }
          ]
        }
      ]
    }
  }
}

Semantics for blinds example

The following example shows a Discover.Response message for blinds that support the Alexa.RangeController interface and uses semantics. Use the Alexa.RangeController interface for blinds that can raise and lower to a range of positions. If your blinds only fully open and fully close, use the ModeController interface instead. You can use the Alexa.RangeController interface for your add-ons that control blinds in the following locales: de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, pt_BR.

Show/hide discovery response

{
  "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": "Blinds manufacturer name",
          "description": "description that appears in the Alexa app",
          "friendlyName": "device name that appears in the Alexa app",
          "displayCategories": ["INTERIOR_BLIND"],
          "additionalAttributes":  {
            "manufacturer" : "Blinds manufacturer name",
            "model" : "Sample Model",
            "serialNumber": "the serial number",
            "customIdentifier": "your custom identifier"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "instance": "Blind.Lift",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.Opening"
                    }
                  }
                ]
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 0,
                  "maximumValue": 100,
                  "precision": 1
                },
                "unitOfMeasure": "Alexa.Unit.Percent"
              },
              "semantics": {
                "actionMappings": [
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Close"],
                    "directive": {
                      "name": "SetRangeValue",
                      "payload": {
                        "rangeValue": 0
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Open"],
                    "directive": {
                      "name": "SetRangeValue",
                      "payload": {
                        "rangeValue": 100
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Lower"],
                    "directive": {
                      "name": "AdjustRangeValue",
                      "payload": {
                        "rangeValueDelta" : -10,
                        "rangeValueDeltaDefault" : false
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Raise"],
                    "directive": {
                      "name": "AdjustRangeValue",
                      "payload": {
                        "rangeValueDelta" : 10,
                        "rangeValueDeltaDefault" : false
                      }
                    }
                  }
                ],
                "stateMappings": [
                  {
                    "@type": "StatesToValue",
                    "states": ["Alexa.States.Closed"],
                    "value": 0
                  },
                  {
                    "@type": "StatesToRange",
                    "states": ["Alexa.States.Open"],
                    "range": {
                      "minimumValue": 1,
                      "maximumValue": 100
                    }
                  }  
                ]
              }
            },
            {
              "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 PowerController interface and both the Alexa.RangeController and ToggleController interfaces.

Show/hide discovery response

{
  "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": "Fan manufacturer name",
          "description": "Tower Fan by Sample Manufacturer",
          "friendlyName": "Tower Fan",
          "displayCategories": ["FAN"],
          "additionalAttributes":  {
            "manufacturer" : "Fan manufacturer name",
            "model" : "Sample Model",
            "serialNumber": "the serial number",
            "customIdentifier": "your custom identifier"
          },
          "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.RangeController interface directives to your add-on.

SetRangeValue directive

Support the SetRangeValue directive so that users can set the level of features on devices. The following examples show user utterances:

SetRangeValue directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "Fan.Speed",
      "name": "SetRangeValue",
      "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": {
      "rangeValue": 7
    }
  }
}

SetRangeValue directive payload

Property	Description	Type	Required
`rangeValue`	Value to set the feature of the device to.	Number	Yes

SetRangeValue response

If you handle a SetRangeValue 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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": 7,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SetRangeValue directive error handling

If you can’t handle a SetRangeValue directive successfully, respond with an Alexa.ErrorResponse event. If your error is safety related, respond with an Alexa.Safety.ErrorResponse.

AdjustRangeValue directive

Support the AdjustRangeValue directive so that users can adjust the level of features on devices. The following examples show user utterances:

AdjustRangeValue directive example

The following example shows an AdjustRangeValue directive that Alexa sends to your add-on.

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "Fan.Speed",
      "name": "AdjustRangeValue",
      "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": {
      "rangeValueDelta": -5,
      "rangeValueDeltaDefault": false
    }
  }
}

AdjustRangeValue directive payload

Property	Description	Type	Required
`rangeValueDelta`	Amount by which to change the feature of the device. If the user doesn’t specify the amount, the value defaults to `precision`.	Number	Yes
`rangeValueDeltaDefault`	Set to `false`, if the user specified the amount of the change.	Boolean	Yes

AdjustRangeValue response event

If you handle an AdjustRangeValue 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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": 10,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

AdjustRangeValue directive error handling

If you can’t handle an AdjustRangeValue 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 about the features of their devices. The following examples show some user utterances:

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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": 4,
        "timeOfSample": "2017-02-03T16:21:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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.RangeController",
            "instance": "Fan.Speed",
            "name": "rangeValue",
            "value": 0,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "OFF",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:00.00Z",
    "uncertaintyInMilliseconds": 60000
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Properties and objects

RangeValue property

Preset object

PresetResources object

Semantics

Use semantics to enable additional utterances

Use semantics to enable announcements

Discovery

Capabilities array

Discovery response examples

Fan example

Semantics for blinds example

Range and toggle controllers example

Directives

SetRangeValue directive

SetRangeValue directive example

SetRangeValue directive payload

SetRangeValue response

SetRangeValue directive error handling

AdjustRangeValue directive

AdjustRangeValue directive example

AdjustRangeValue directive payload

AdjustRangeValue response event

AdjustRangeValue directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Properties and objects

​RangeValue property

​Preset object

​PresetResources object

​Semantics

​Use semantics to enable additional utterances

​Use semantics to enable announcements

​Discovery

​Capabilities array

​Discovery response examples

​Fan example

​Semantics for blinds example

​Range and toggle controllers example

​Directives

​SetRangeValue directive

​SetRangeValue directive example

​SetRangeValue directive payload

​SetRangeValue response

​SetRangeValue directive error handling

​AdjustRangeValue directive

​AdjustRangeValue directive example

​AdjustRangeValue directive payload

​AdjustRangeValue response event

​AdjustRangeValue directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Properties and objects

RangeValue property

Preset object

PresetResources object

Semantics

Use semantics to enable additional utterances

Use semantics to enable announcements

Discovery

Capabilities array

Discovery response examples

Fan example

Semantics for blinds example

Range and toggle controllers example

Directives

SetRangeValue directive

SetRangeValue directive example

SetRangeValue directive payload

SetRangeValue response

SetRangeValue directive error handling

AdjustRangeValue directive

AdjustRangeValue directive example

AdjustRangeValue directive payload

AdjustRangeValue response event

AdjustRangeValue directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics