Alexa.ThermostatController Interface
Implement the Alexa.ThermostatController
interface in your Alexa skill so that users can control smart thermostats. A thermostat can control devices, such as furnaces, air conditioners, ceiling fans, and water heaters. For details about Smart Home skills, see Understand Smart Home Skills.
A thermostat is a device that senses temperature, and attempts to keep the temperature at a specified setpoint or within a specified temperature range. You can use the ThermostatController
interface for devices with up to two setpoints, different thermostat modes, and programmable thermostat schedules. Typically you use the ThermostatController
interface with the Alexa.TemperatureSensor
interface.
Implement the other Alexa.ThermostatController
interfaces based on the features that your device supports:
- To download the HVAC configuration from the Alexa app to your thermostat, implement the
Alexa.ThermostatController.Configuration
interface. - To enable a customer to set a temperature schedule on your thermostat, implement the
Alexa.ThermostatController.Schedule
interface. - To enable Alexa to estimate the energy use of a thermostat or HVAC system, implement the
Alexa.ThermostatController.HVAC.Components
interface.
For the list of languages that the ThermostatController
interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
When you use the Alexa.ThermostatController
interface, the Alexa service provides the voice interaction model for you. The following examples show some user utterances:
Alexa, set thermostat to twenty.
Alexa, set the AC to seventy-five.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
Alexa, set thermostat to automatic.
Alexa, turn off the heat.
Alexa, resume thermostat schedule.
Alexa, what mode is my thermostat set to?
After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your skill.
Thermostat setpoint types
Alexa supports thermostats with one or two setpoints.
- Single-setpoint thermostats
- A single-setpoint thermostat has a single temperature setting that it attempts to maintain. For example, a thermostat with a single setpoint might turn on the furnace when the temperature falls below the setpoint, and turn off the furnace when the temperature rises above the setpoint.
- Dual-setpoint thermostats
- A dual-setpoint thermostat has two temperature settings, a lower and upper setpoint. The thermostat maintains the temperature within the range between the setpoints.
A thermostat can support different setpoints when in different modes. For details, see properties.
Thermostat scheduling
If your device supports a user request to set the temperature or thermostat mode on a weekly schedule, implement the Alexa.ThermostatController.Schedule
interface.
Adaptive recovery
A thermostat that supports adaptive recovery starts the HVAC system early enough to reach the programmed temperature on schedule.
If your skill implements the Alexa.ThermostatController.Schedule
and your device supports adaptive recovery, you report pre-heating or pre-cooling in progress. After the temperature reaches the target setpoint, you report that adaptive recovery is inactive. For example, if the target heating temperature is 70°F at 6:00 PM, the thermostat might start heating at 5:55 PM. After you report the state change, the Alexa app displays a visual cue that pre-heating or pre-cooling is in progress.
The customer can enable and disable adaptive recovery in the Alexa.ThermostatController.Schedule
interface.
Properties
The following table shows the properties that the Alexa.ThermostatController
interface defines. You identify the properties that you support in your discovery response. All the properties are optional. Include only the properties that match the components of your thermostat device.
Property | Description | Type |
---|---|---|
targetSetpoint |
The thermostat should maintain the temperature at this setpoint. Single-setpoint thermostats use this property. | Temperature |
lowerSetpoint |
The thermostat should maintain the temperature above this setpoint. Dual-setpoint thermostats use this property. | Temperature |
upperSetpoint |
The thermostat should maintain the temperature below this setpoint. Dual-setpoint thermostats use this property. | Temperature |
thermostatMode |
The current mode of the thermostat. | ThermostatMode |
adaptiveRecoveryStatus |
The current status of pre-heating or pre-cooling. Valid values: PREHEATING , PRECOOLING , INACTIVE . |
String |
A thermostat can support different setpoints when in different modes. For example, a thermostat might support only a target setpoint when in HEAT
or COOL
mode, and support lower and upper setpoints when in AUTO
or ECO
mode.
Discovery
You describe endpoints that support Alexa.ThermostatController
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.
Use THERMOSTAT
for the display category. For the full list of display categories, see display categories.
Configuration object
In addition to the usual discovery response fields, for ThermostatController
, include a configuration object that contains the following fields.
supportsScheduling
property is deprecated. To support scheduling, implement the Alexa.ThermostatController.Schedule
interface instead.Field | Description | Type | Required |
---|---|---|---|
supportedModes |
The modes that the device supports. | An array of thermostat mode strings. | No |
supportsScheduling |
Set to true if a user can specify a setpoint for an amount of time. For example, the user can set the temperature to 70 degrees for 30 minutes. The default is false . |
Boolean | No |
Discover response example
The following example shows a Discover.Response
message for an Alexa skill that controls a thermostat and supports the Alexa.ThermostatController
and Alexa.TemperatureSensor
interfaces. In this example, the endpoint is a dual-setpoint thermostat, with three modes.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "Smart Thermostat by Thermostat Maker",
"friendlyName": "Hallway Thermostat",
"displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.ThermostatController",
"version": "3.1",
"properties": {
"supported": [{
"name": "lowerSetpoint"
},
{
"name": "upperSetpoint"
},
{
"name": "thermostatMode"
},
{
"name": "adaptiveRecoveryStatus"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedModes": ["HEAT", "COOL", "AUTO"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.TemperatureSensor",
"version": "3",
"properties": {
"supported": [{
"name": "temperature"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Discover response example for an air conditioner
Typically air conditioners support a single setpoint, and only have a cooling mode. Unlike thermostats, which are usually on all the time, users turn air conditioners on and off. For an air conditioner, Amazon recommends that you also implement the Alexa.PowerController
interface, and keep the PowerController
synchronized with the ThermostatController
as shown in the following list:
- When the thermostat controller mode is set to
COOL
, the power controller power state is set toON
. - When the thermostat controller mode is set to
OFF
, the power controller power state is set toOFF
.
The following example shows a Discover.Response
message for an Alexa skill that controls an air conditioner and supports the ThermostatController
and Alexa.PowerController
interfaces. You don't need to implement the Alexa.TemperatureSensor
interface unless your air conditioner displays the temperature.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "Smart Air Conditioner",
"friendlyName": "Living room A/C",
"displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.ThermostatController",
"version": "3.1",
"properties": {
"supported": [{
"name": "targetSetpoint"
},
{
"name": "thermostatMode"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedModes": ["OFF", "COOL"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
SetTargetTemperature directive
Support the SetTargetTemperature
directive so that users can specify the temperature that they want a thermostat to maintain. The user can optionally specify the duration for the new temperature setting.
The following examples show user utterances:
Alexa, set bedroom thermostat to twenty.
Alexa, set living room air conditioner to seventy-five.
Alexa, set the kitchen AC to twenty-five degrees for four hours.
SetTargetTemperature directive example (single-setpoint thermostat)
The following example shows a SetTargetTemperature
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetTargetTemperature",
"messageId": "a unique identifier",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"targetSetpoint": {
"value": 20.0,
"scale": "CELSIUS"
}
}
}
}
SetTargetTemperature directive example (dual-setpoint thermostat)
The following example shows a SetTargetTemperature
directive that Alexa sends to your skill for a dual-setpoint thermostat.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetTargetTemperature",
"messageId": "a unique identifier",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"lowerSetpoint": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"upperSetpoint": {
"value": 72.0,
"scale": "FAHRENHEIT"
}
}
}
}
SetTargetTemperature directive payload
schedule
property is deprecated. To support scheduling, implement the Alexa.ThermostatController.Schedule
interface instead.Field | Description | Type |
---|---|---|
targetSetpoint |
Thermostat should maintain the temperature at this setpoint. The directive includes this field for single-setpoint thermostats. | Temperature object |
lowerSetpoint |
Thermostat should maintain the temperature above this setpoint. The directive includes this field for dual-setpoint thermostats. | Temperature object |
upperSetpoint |
Thermostat should maintain the temperature below this setpoint. The directive includes this field for dual-setpoint thermostats. | Temperature object |
schedule |
Duration of time that the thermostat should maintain the specified setpoints. Apply the new setpoints immediately, for the duration specified. This field is only included if the user specifies it, and you indicated that you support it in your discovery response. | TimeInterval object |
SetTargetTemperature response
If you handle a SetTargetTemperature
directive successfully, respond with an Alexa.Response
event. In the context object, include the values of all relevant properties.
SetTargetTemperature response event example (single-setpoint thermostat)
The following example shows a SetTargetTemperature
response for a single-setpoint thermostat.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.3,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
SetTargetTemperature response event example (dual-setpoint thermostat)
The following example shows a SetTargetTemperature
response for a dual-setpoint thermostat.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "AUTO",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "lowerSetpoint",
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "upperSetpoint",
"value": {
"value": 72.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 66.5,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
SetTargetTemperature directive error handling
If you can't handle a SetTargetTemperature
directive successfully, respond with an Alexa.ThermostatController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to temperature or thermostats.
AdjustTargetTemperature directive
Support the AdjustTargetTemperature
directive so that users can adjust the temperature that they want a thermostat to maintain.
The following examples show user utterances:
Alexa, make it warmer in here.
Alexa, make it cooler in here.
AdjustTargetTemperature directive example
The following example shows an AdjustTargetTemperature
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "AdjustTargetTemperature",
"messageId": "a unique identifier",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"targetSetpointDelta": {
"value": -2.0,
"scale": "CELSIUS"
}
}
}
}
AdjustTargetTemperature directive payload
Field | Description | Type |
---|---|---|
targetSetpointDelta |
Amount by which to change the temperature. The amount can be positive or negative. | Temperature object |
AdjustTargetTemperature response
If you handle an AdjustTargetTemperature
directive successfully, respond with an Alexa.Response
event. In the context object, include the values of all relevant properties.
The following example shows an AdjustTargetTemperature
response for a single-setpoint thermostat.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 20.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
AdjustTargetTemperature directive error handling
If you can't handle an AdjustTargetTemperature
directive successfully, respond with an Alexa.ThermostatController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to temperature or thermostats.
SetThermostatMode directive
Support the SetThermostatMode
directive so that users can set the mode of a device. The user must say, "Alexa, set the [user thermostat device name] to [available mode]."
SetThermostatMode directive example
The following example shows a SetThermostatMode
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetThermostatMode",
"messageId": "a unique identifier",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"thermostatMode" : {
"value": "COOL"
}
}
}
}
SetThermostatMode directive payload
Field | Description | Type |
---|---|---|
thermostatMode |
Mode to set for the thermostat. | ThermostatMode object |
SetThermostatMode response event
If you handle a SetThermostatMode
directive successfully, respond with an Alexa.Response
event. In the context object, include the values of all relevant properties.
The following example shows a SetThermostatMode
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 17.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
SetThermostatMode directive error handling
If you can't handle a SetThermostatMode
directive successfully, respond with an Alexa.ThermostatController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to temperature or thermostats.
ResumeSchedule directive
Support the ResumeSchedule
directive so that users can resume the programmed schedule of their thermostat after they overrode it. For example, a user might use the vacation override when they go away, and resume the normal program when they return.
ResumeSchedule directive example
The following example shows a ResumeSchedule
directive that Alexa sends to your skill to resume the thermostat schedule.
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "ResumeSchedule",
"messageId": "a unique identifier",
"correlationToken": "an opaque correlation token",
"payloadVersion": "3.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {}
}
}
ResumeSchedule directive payload
The ResumeSchedule
directive doesn't define a payload.
ResumeSchedule response
If you handle a ResumeSchedule
directive successfully, respond with an Alexa.Response
event. In the context object, include the values of all relevant properties.
The following example shows a ResumeSchedule
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 17.9,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
ResumeSchedule directive error handling
If you can't handle a ResumeSchedule
directive successfully, respond with an Alexa.ThermostatController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to temperature or thermostats.
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 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.
StateReport response example
The following example shows a StateReport
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.9,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
StateReport response example for an air conditioner
The following example shows a StateReport
response for an air conditioner.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "correlation token received in the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20.0,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "adaptiveRecoveryStatus",
"value": "INACTIVE",
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"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
The following example shows a ChangeReport
event.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "a unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18.0,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.1,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 0
}]
}
}
ChangeReport air conditioner example
The following example shows a ChangeReport
event for an air conditioner.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "a unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {
"change": {
"cause": {
"type": "RULE_TRIGGER"
},
"properties": [{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18.0,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "adaptiveRecoveryStatus",
"value": "PRECOOLING",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.1,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2020-02-26T18:20:50Z",
"uncertaintyInMilliseconds": 0
}]
}
}
Requiring user verification
ja-JP
locale.When a user attempts to set a temperature or change the thermostat mode, you can optionally require the user to verify the action before Alexa performs it. To require user verification, specify which directives you require verification for in your Discover.Response
. For details, see the verificationsRequired object and example for a thermostat that requires user verification.
The following example shows a sample conversation when you require user verification:
Alexa, set the temperature to sixty-five degrees on the living room air conditioner.
Set living room air conditioner to sixty-five degrees?
Yes.
OK, living room air conditioner is set to sixty-five degrees.
アレクサ、リビングのエアコンを25度にして。
リビングのエアコンで、設定温度を25度にするんですね?
はい。
リビングのエアコンを冷房25度に設定しました。