Alexa.ThermostatController Interface 3.2

  • 3.2
  • 3

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

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

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, what mode is my thermostat set to?
Alexa, what's the temperature in here?
Alexa, what is the temperature of the house?
Alexa, resume thermostat schedule.

Alexa, règle le thermostat sur vingt.
Alexa, règle la climatisation sur soixante-quinze.
Alexa, rends plus chaud ici.
Alexa, rends moins chaud ici.
Alexa, mets le thermostat en mode automatique.
Alexa, éteins le chauffage.
Alexa, sur quel mode est réglé mon thermostat?
Alexa, quelle est la température ici?
Alexa, quelle est la température de la maison?

Alexa, stelle Thermostat auf zwanzig.
Alexa, stelle die Klimaanlage auf fünfundsiebzig.
Alexa, mache es hier drin wärmer.
Alexa, mache es hier drin kühler.
Alexa, stelle Thermostat auf Automatik.
Alexa, schalte die Heizung aus.
Alexa, auf welchen Modus ist mein Thermostat eingestellt?
Alexa, wie ist die Temperatur hier drin?
Alexa, was ist die Temperatur von dem Haus?

Alexa, थर्मोस्टेट को बीस पर सेट करो।
Alexa, AC को पचहत्तर पर सेट करो।
Alexa, इसे यहाँ गर्म करो।
Alexa, इसे यहाँ ठंडा करो।
Alexa, थर्मोस्टैट को स्वचालित पर सेट करें।
Alexa, आँच बंद कर दो।
Alexa, मेरा थर्मोस्टेट किस मोड पर सेट है?
Alexa, यहाँ का तापमान क्या है?
Alexa, घर का तापमान क्या है?

Alexa, imposta il termostato su venti.
Alexa, imposta il conditionatore a settantacinque.
Alexa, alza la temperatura nel soggiorno.
Alexa, abbassa la temperatura nel soggiorno.
Alexa, imposta il termostato su automatico.
Alexa, spegni il riscaldamento.
Alexa, su quale modalità è impostato il mio termostato?
Alexa, qual è la temperatura qui?
Alexa, qual è la temperatura della casa?

アレクサ、サーモスタットを20度にして
アレクサ、エアコンを25度にして
アレクサ、この部屋を暖かくして
アレクサ、この部屋を涼しくして
アレクサ、サーモスタットを自動にして
アレクサ、暖房を消して
アレクサ、サーモスタットのモードはなに？
アレクサ、ここの温度は？
アレクサ、家の温度は？

Alexa, muda o termostato para vinte.
Alexa, muda o ar condicionado para setenta e cinco.
Alexa, torne mais quente aqui.
Alexa, torne mais fresco aqui.
Alexa, muda o termostato para automático.
Alexa, desligue o aquecimento.
Alexa, apague o calor.
Alexa, a que modo está ajustado o meu termostato?
Alexa, qual é a temperatura aqui?
Alexa, qual é a temperatura da casa?

Alexa, pon el termostato a veinte.
Alexa, pon el aire acondicionado a setenta y cinco.
Alexa, haz más cálido aquí.
Alexa, haz más fresco aquí.
Alexa, pon el termostato en automático.
Alexa, apaga la calefacción.
Alexa, ¿en qué modo está mi termostato?
Alexa, ¿cuál es la temperatura aquí?
Alexa, ¿cuál es la temperatura de la casa?

Alexa, zet de thermostaat op twintig.
Alexa, zet de airco op vijfenzeventig.
Alexa, maak het hier warmer.
Alexa, maak het hier koeler.
Alexa, zet de thermostaat op automatisch.
Alexa, zet de verwarming uit.
Alexa, wat is de modus van mijn thermostaat?
Alexa, wat is de temparatuur hier?
Alexa, wat is de temparatuur van het huis?.
Alexa, hervat het thermostaatschema.

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 "Alexa, set the thermostat to seventy-two degrees for thirty minutes." 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 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.

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 when it's really 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 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.

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.
Include at least one of HEAT or COOL thermostat modes.		 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 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.

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

Directives

Alexa sends the following Alexa.ThermostatController interface directives to your skill.

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, règle le thermostat de la chambre sur vingt.
Alexa, règle le climatiseur du salon sur soixante-quinze.

Alexa, stelle Schlafzimmerthermostat auf zwanzig.
Alexa, stelle die Wohnzimmerklimaanlage auf fünfundsiebzig.

Alexa, बेडरूम थर्मोस्टेट को बीस पर सेट करो
Alexa, लिविंग रूम के एयर कंडीशनर को पचहत्तर पर सेट करो

Alexa, imposta il termostato della camera da letto su venti.
Alexa, imposta il condizionatore d'aria del soggiorno a settantacinque.

アレクサ、寝室のサーモスタットを20度にして
アレクサ、リビングのエアコンを25度にして

Alexa, muda o termostato do quarto para vinte.
Alexa, muda o ar condicionado da sala de estar para setenta e cinco.

Alexa, pon el termostato del dormitorio a veinte.
Alexa, pon el aire acondicionado de la sala a setenta y cinco.

Alexa, zet de thermostaat in de slaapkamer op twintig.
Alexa, zet de airco in de woonkamer op vierentwintig.

SetTargetTemperature directive examples

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

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

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.

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

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, increase the thermostat temperature by 3 degrees.
Alexa, decrease the thermostat temperature by 3 degrees.
Alexa, increase the AC temperature.
Alexa, decrease the AC temperature.

Alexa, augmente la température du thermostat de trois degrés.
Alexa, diminue la température du thermostat de trois degrés.
Alexa, augmente la température du climatiseur.
Alexa, diminue la température du climatiseur.

Alexa, erhöhe die Thermostattemperatur um 3 Grad.
Alexa, senke die Thermostattemperatur um 3 Grad.
Alexa, erhöhe die AC-Temperatur.
Alexa, senke die AC-Temperatur.

Alexa, थर्मोस्टेट का तापमान 3 डिग्री बढ़ा दें
Alexa, थर्मोस्टेट का तापमान 3 डिग्री कम करें
Alexa,एसी का तापमान बढ़ाओ
Alexa,एसी का तापमान कम करो

Alexa, aumenta la temperatura del termostato di 3 gradi.
Alexa, diminuisci la temperatura del termostato di 3 gradi.
Alexa, aumenta la temperatura dell'aria condizionata.
Alexa, abbassa la temperatura dell'aria condizionata.

アレクサ、エアコンの温度を3度上げて
アレクサ、エアコンの温度を3度下げて
アレクサ、エアコンの温度を上げて
アレクサ、エアコンの温度を下げて

Alexa, aumentar a temperatura do termostato em três graus.
Alexa, diminuir a temperatura do termostato em três graus.
Alexa, aumentar a temperatura do ar condicionado.
Alexa, diminuir a temperatura do ar condicionado.

Alexa, sube la temperatura del termostato 3 grados.
Alexa, baja la temperatura del termostato 3 grados.
Alexa, aumenta la temperatura del aire acondicionado.
Alexa, disminuye la temperatura del aire acondicionado.

Alexa, verhoog de temparatuur van de thermostaat met 3 graden.
Alexa, verlaag de temparatuur van de thermostaat met 3 graden.
Alexa, verhoog de temperatuur van de airco.
Alexa, verlaag de temperatuur van de airco.

AdjustTargetTemperature directive example

The following example shows an AdjustTargetTemperature directive that Alexa sends to your skill.

{
  "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. In the context object, include the values of all relevant properties.

The following example shows an AdjustTargetTemperature response for a single-setpoint thermostat.

Copied to clipboard.

{
  "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, "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": "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. In the context object, include the values of all relevant properties.

The following example shows a SetThermostatMode response.

Copied to clipboard.

{
  "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:

Alexa, resume thermostat schedule.

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": "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. In the context object, include the values of all relevant properties.

The following example shows a ResumeSchedule response.

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

{
    "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:

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度に設定しました。

Was this page helpful?

Last updated: Dec 19, 2024