Alexa.ThermostatController Interface 3

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.

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:

English (All)

After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your add-on.

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

If your device supports a user request to set the temperature or thermostat mode on a weekly schedule, implement the Alexa.ThermostatController.Schedule interface.

Reportable 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`

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

Configuration object

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

Field	Description	Type	Required
`supportedModes`	Modes that the device supports.	Array of `ThermostatMode` 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 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.

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.1",
                        "properties": {
                            "supported": [{
                                    "name": "lowerSetpoint"
                                },
                                {
                                    "name": "upperSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "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.1",
                        "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.

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.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.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:

English (All)

SetTargetTemperature directive example (single-setpoint thermostat)

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "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 add-on for a dual-setpoint thermostat.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "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

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 included only 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. The following example shows a SetTargetTemperature response for a 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-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                 "timeOfSample": "2024-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.3,
                    "scale": "CELSIUS"
                },
                 "timeOfSample": "2024-02-03T16:15:00.00Z",
                "uncertaintyInMilliseconds": 300000
            }
        ]
    }
}

The following example shows a SetTargetTemperature response for a 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-02-03T16:20:48.00Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "lowerSetpoint",
                "value": {
                    "value": 68.0,
                    "scale": "FAHRENHEIT"
                },
                "timeOfSample": "2017-01-13T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "upperSetpoint",
                "value": {
                    "value": 72.0,
                    "scale": "FAHRENHEIT"
                },
                "timeOfSample": "2017-01-13T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 66.5,
                    "scale": "FAHRENHEIT"
                },
                "timeOfSample": "2024-02-03T16:15:00.00Z",
                "uncertaintyInMilliseconds": 300000
            }
        ]
    }
}

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:

English (All)

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.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": "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-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
         "timeOfSample": "2024-02-03T16:08:15.02Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
         "timeOfSample": "2024-02-03T16:10:15.02Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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.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": "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-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 17.0,
          "scale": "CELSIUS"
        },
         "timeOfSample": "2024-02-03T16:20:44:48Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.0,
          "scale": "CELSIUS"
        },
         "timeOfSample": "2024-02-03T16:20:43:48Z",
        "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 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.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": "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-02-03T16:20:50.52Z",
        "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-02-03T16:25:31.22Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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-01-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                 "timeOfSample": "2024-01-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.9,
                    "scale": "CELSIUS"
                },
                 "timeOfSample": "2024-02-03T16:19:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                 "timeOfSample": "2024-02-03T16:20:00.00Z",
                "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-01T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2020-07-01T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2020-07-26T16:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-07-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": "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": "COOL",
            "timeOfSample": "2020-07-01T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-07-01T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.TemperatureSensor",
            "name": "temperature",
            "value": {
              "value": 19.1,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-07-26T30:20:50Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {
      "properties": [{
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-07-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": "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.TemperatureSensor",
                    "name": "temperature",
                    "value": {
                        "value": 19.1,
                        "scale": "CELSIUS"
                    },
                    "timeOfSample": "2020-07-26T08:00:10Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "COOL",
                "timeOfSample": "2020-07-01T18:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 18.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2020-07-01T18:20:50Z",
                "uncertaintyInMilliseconds": 500
            }, {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-07-26T08:00:50Z",
                "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

​Utterances

​Thermostat setpoint types

​Thermostat scheduling

​Reportable properties

​Discovery

​Configuration object

​Discover response example

​Discover response example for an air conditioner

​Directives

​SetTargetTemperature directive

​SetTargetTemperature directive example (single-setpoint thermostat)

​SetTargetTemperature directive example (dual-setpoint thermostat)

​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

Utterances

Thermostat setpoint types

Thermostat scheduling

Reportable properties

Discovery

Configuration object

Discover response example

Discover response example for an air conditioner

Directives

SetTargetTemperature directive

SetTargetTemperature directive example (single-setpoint thermostat)

SetTargetTemperature directive example (dual-setpoint thermostat)

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