Alexa.ThermostatController Interface 3.2

Implement the Alexa.ThermostatController interface in your Alexa add-on so that users can control smart thermostats. A thermostat can control devices, such as furnaces, air conditioners, and water heaters. For more details about smart home add-ons, see Connect Your Device Cloud with Smart Home Add-ons. 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 heating, ventilation, and air conditioning (HVAC) system 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Version changes

This version adds support for adaptive recovery and a new thermostat mode, called emergency heating.

Utterances

When you use the Alexa.ThermostatController interface, the Alexa service provides the voice interaction model for you. After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your add-on. The following examples show some user utterances:

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 Reportable properties.

Thermostat scheduling

When a user sets a temperature, they can specify a hold duration. For example, a user can say If your device supports hold durations, you specify it in your discovery response. 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 add-on 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.

Reportable properties

The Alexa.ThermostatController interface defines the following reportable properties. 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` object
`lowerSetpoint`	The thermostat should maintain the temperature above this setpoint. Dual-setpoint thermostats use this property.	`Temperature` object
`upperSetpoint`	The thermostat should maintain the temperature below this setpoint. Dual-setpoint thermostats use this property.	`Temperature` object
`thermostatMode`	The current mode of the thermostat.	`ThermostatMode` object
`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.

ThermostatMode values

The following table shows the mode values for thermostats. A thermostat might not support all modes.

Value	Description
`AUTO`	Automatic heating or cooling based on the current temperature and the setpoint.
`COOL`	Cooling mode.
`ECO`	Economy mode.
`EM_HEAT`	Emergency heating mode. This mode uses a backup heat source as an additional heat source. For example, a customer might use emergency heat in extreme cold or when the heat pump is broken. Customers can set this mode in device settings in the Alexa app.
`HEAT`	Heating mode.
`OFF`	Heating and cooling are off, but the device might still have power.

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 add-on 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. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Configuration object

In addition to the usual discovery response fields, for Alexa.ThermostatController, include a configuration object that contains the following fields.

Field	Description	Type	Required
`supportedModes`	Indicates the modes that the device supports. You must include at least one of `HEAT` or `COOL` thermostat modes.	Array of `ThermostatMode` strings	Yes
`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 add-on 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.

Dual setpoint thermostat example

{
    "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 of the endpoint",
                "description": "Smart Thermostat by Thermostat Maker",
                "friendlyName": "Hallway Thermostat",
                "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "lowerSetpoint"
                                },
                                {
                                    "name": "upperSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                },
                                {
                                    "name": "adaptiveRecoveryStatus"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": ["HEAT", "COOL", "AUTO", "EM_HEAT"],
                            "supportsScheduling": true
                        }
                    },
                    {
                        "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 to ON.
When the thermostat controller mode is set to OFF, the power controller power state is set to OFF.

The following example shows a Discover.Response message for an Alexa add-on that controls an air conditioner and supports the ThermostatController and Alexa.PowerController interfaces. The response includes the Alexa.TemperatureSensor interface for an air conditioner that displays the temperature.

Air conditioner example

{
    "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 of the endpoint",
                "description": "Smart Air Conditioner",
                "friendlyName": "Living room A/C",
                "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "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.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

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

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:

SetTargetTemperature directive examples

The following example shows a SetTargetTemperature directive that Alexa sends to your add-on for a single-setpoint thermostat.

Single-setpoint thermostat example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      },
      "holdUntil": {
        "start":"2017-10-04T14:00Z",
        "end":"2017-10-04T14:15Z"
      }
    }
  }
}

The following example shows a SetTargetTemperature directive that Alexa sends to your add-on for a dual-setpoint thermostat.

Dual-setpoint thermostat example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "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"
      },
      "holdUntil": {
        "duration": "PT30M"
      }
    }
  }
}

SetTargetTemperature directive payload

Property	Description	Type	Required
`targetSetpoint`	Thermostat should maintain the temperature at this setpoint. Alexa includes this field for single-setpoint thermostats.	`Temperature` object	No
`lowerSetpoint`	Thermostat should maintain the temperature above this setpoint. Alexa includes this field for dual-setpoint thermostats.	`Temperature` object	No
`upperSetpoint`	Thermostat should maintain the temperature below this setpoint. Alexa includes this field for dual-setpoint thermostats.	`Temperature` object	No
`holdUntil`	Duration of time that the thermostat should maintain the specified setpoints. Apply the new setpoints for the duration specified. Alexa includes this field if the user specifies it and you indicated that you support it in your discovery response.	`TimeInterval` object	No

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. The following example shows a SetTargetTemperature response for a single-setpoint thermostat.

Single-setpoint thermostat example

{
    "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": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2024-01-01T08:00:00.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2024-01-01T08:00:00.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.3,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2024-01-21T08:00:00.12Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    }
}

The following example shows a SetTargetTemperature response for a dual-setpoint thermostat.

Dual-setpoint thermostat example

{
  "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": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "lowerSetpoint",
        "value": {
          "value": 68.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "upperSetpoint",
        "value": {
          "value": 72.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 66.5,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "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:

AdjustTargetTemperature directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "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. A successful response confirms that the endpoint completed the requested action. 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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-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,

SetThermostatMode directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

SetThermostatMode directive payload

Field	Description	Type
`thermostatMode`	Heating and cooling modes for a thermostat.	Object
`thermostatMode.value`	Mode to set for the thermostat. For valid values, see `ThermostatMode`.	String

SetThermostatMode response event

If you handle a SetThermostatMode directive successfully, respond with an Alexa.Response event. A successful response confirms that the endpoint completed the requested action. 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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2024-07-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 17.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-07-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-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 on the thermostat after they overrode the schedule. For example, a user might use the vacation override when they go away, and resume the normal program when they return. The following example shows a user utterance:

English (US)

ResumeSchedule directive example

The following example shows a ResumeSchedule directive that Alexa sends to your add-on to resume the thermostat schedule.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ResumeSchedule",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "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. A successful response confirms that the endpoint completed the requested action. 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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2024-07-01T08:00:00.12Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 17.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-07-01T08:00:00.12Z",
        "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": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches 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": "2024-07-01T08:00:00.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2024-07-01T08:00:00.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.9,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2024-07-06T15:02:00.12Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2024-07-06T15:00:00.12Z",
                "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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches 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:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2020-02-26T18:20:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.ThermostatController",
          "name": "adaptiveRecoveryStatus",
          "value": "INACTIVE",
          "timeOfSample": "2020-02-26T18:20:00.00Z",
          "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2020-02-26T18:20:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-02-26T18: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

The following example shows a ChangeReport event.

{  
  "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.ThermostatController",
            "name": "thermostatMode",
            "value": "EM_HEAT",
            "timeOfSample": "2024-01-01T08:00:00.05Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2024-01-01T08:00:00.05Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.TemperatureSensor",
            "name": "temperature",
            "value": {
              "value": 19.1,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2024-01-01T08:00:00.05Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {
      "properties": [{
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2024-01-01T07:50:00.00Z",
          "uncertaintyInMilliseconds": 0
      }]
  }
}

ChangeReport air conditioner example

The following example shows a ChangeReport event for an air conditioner.

{
    "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": "RULE_TRIGGER"
                },
                "properties": [{
                        "namespace": "Alexa.ThermostatController",
                        "name": "thermostatMode",
                        "value": "COOL",
                        "timeOfSample": "2024-07-01T08:00:00.12Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.ThermostatController",
                        "name": "targetSetpoint",
                        "value": {
                            "value": 18.0,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2024-07-01T08:00:00.12Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.ThermostatController",
                        "name": "adaptiveRecoveryStatus",
                        "value": "PRECOOLING",
                        "timeOfSample": "2024-07-01T08:00:00.12Z",
                        "uncertaintyInMilliseconds": 1000
                    },
                    {
                        "namespace": "Alexa.TemperatureSensor",
                        "name": "temperature",
                        "value": {
                            "value": 19.1,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2024-07-01T08:01:00.00Z",
                        "uncertaintyInMilliseconds": 0
                    }
                ]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2024-06-30T23:59:00.32Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Requiring user verification

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:

English (All)
Japanese

​Version changes

​Utterances

​Thermostat setpoint types

​Thermostat scheduling

​Adaptive recovery

​Reportable properties

​ThermostatMode values

​Discovery

​Configuration object

​Discover response example

​Discover response example for an air conditioner

​Directives

​SetTargetTemperature directive

​SetTargetTemperature directive examples

​SetTargetTemperature directive payload

​SetTargetTemperature response

​SetTargetTemperature directive error handling

​AdjustTargetTemperature directive

​AdjustTargetTemperature directive example

​AdjustTargetTemperature directive payload

​AdjustTargetTemperature response

​AdjustTargetTemperature directive error handling

​SetThermostatMode directive

​SetThermostatMode directive example

​SetThermostatMode directive payload

​SetThermostatMode response event

​SetThermostatMode directive error handling

​ResumeSchedule directive

​ResumeSchedule directive example

​ResumeSchedule directive payload

​ResumeSchedule response

​ResumeSchedule directive error handling

​State reporting

​StateReport response example

​StateReport response example for an air conditioner

​Change reporting

​ChangeReport event example

​ChangeReport air conditioner example

​Requiring user verification

​Related topics