Alexa.ThermostatController Interface

Implement the Alexa.ThermostatController capability interface so that users can control thermostats. 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 three setpoints, different thermostat modes, and programmable thermostat schedules. Typically you use the ThermostatController interface in conjunction with the Alexa.TemperatureSensor interface.

A thermostat can control devices such as furnaces, air conditioners, ceiling fans, and water heaters.

For the list of locales that are supported for the ThermostatController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.ThermostatController interface, the voice interaction model is already built for you. The following examples show some user utterances:

Alexa, set thermostat to twenty.
Alexa, set the AC to seventy-five.
Alexa, set the AC to twenty-five degrees for four hours.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
Alexa, set thermostat to automatic.
Alexa, turn off the heat.
Alexa, resume thermostat schedule.

After the user says one of these utterances, Alexa sends a corresponding directive to your skill.

Thermostat setpoint types

Alexa supports thermostats with one, two or three 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 may turn on a furnace when the temperature falls below the setpoint, and turn the furnace off 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.
Triple-setpoint thermostats
A triple-setpoint thermostat has three setpoints, a target setpoint, a lower setpoint, and an upper setpoint. The thermostat maintains the temperature within the range between the setpoints, and close to the target setpoint.

A thermostat can support different setpoints when in different modes. For more information, see properties.

Thermostat scheduling

When a user sets a temperature, they can specify a duration for the request (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.

Currently, users can't request to set a temperature or thermostat mode for a time in the future.

Requiring user verification

You can optionally require user verification for Alexa.ThermostatController interface directives such as SetTargetTemperature and SetThermostatMode. See VerificationsRequired and Discover response example for an air conditioner with verification required.

The following example shows a user verification:

Alexa, set the temperature to 65 degrees on the living room air conditioner.
Set living room air conditioner to 65 degrees?
Yes.
OK, living room air conditioner is set to 65 degrees.

アレクサ、リビングのエアコンを25度にして。
リビングのエアコンで、設定温度を25度にするんですね？
はい。
リビングのエアコンを冷房25度に設定しました。

Properties

The Alexa.ThermostatController interface defines the following properties.

Property Description Type
targetSetpoint The thermostat should maintain the temperature at this setpoint. Single- and triple-setpoint thermostats use this property. Temperature
lowerSetpoint The thermostat should maintain the temperature above this setpoint. Dual- and triple-setpoint thermostats use this property. Temperature
upperSetpoint The thermostat should maintain the temperature below this setpoint. Dual- and triple-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 may 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 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.

The 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 The modes that the device supports. An array of thermostatMode strings. No
supportsScheduling 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 endpoint that supports the Alexa.ThermostatController and Alexa.TemperatureSensor interfaces. In this example, the endpoint is a triple-setpoint thermostat, with three modes, and that does not support scheduling.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Thermostat by Thermostat Maker",
          "friendlyName": "Hallway Thermostat",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "lowerSetpoint"
                  },
                  {
                    "name": "upperSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedModes": [ "HEAT", "COOL", "AUTO" ],
                "supportsScheduling": false
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "temperature"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Discover response example for an air conditioner

Typically air conditioners only 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, we recommend that you also implement the Alexa.PowerController interface, and keep the PowerController synchronized with the ThermostatController as shown following:

  • 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 air conditioner that supports the ThermostatController and PowerController interfaces. You do not need to implement the Alexa.TemperatureSensor interface unless your air conditioner displays the temperature.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Air Conditioner",
          "friendlyName": "Living room A/C",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedModes": ["OFF", "COOL"],
                "supportsScheduling": false
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Discover response example for an air conditioner with verification required

The following example is the same as the previous air conditioner example, with user verification added. See VerificationsRequired.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Air Conditioner",
          "friendlyName": "Living room A/C",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedModes": ["OFF", "COOL"],
                "supportsScheduling": false
              },
              "verificationsRequired": [
                {
                  "directive": "SetThermostatMode",
                  "methods": [{
                      "@type": "Confirmation"
                  }]
                },
                {
                  "directive": "SetTargetTemperature",
                  "methods": [{
                      "@type": "Confirmation"
                  }]
                }
              ]
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

SetTargetTemperature directive

Support the SetTargetTemperature directive so that users can specify the temperature that they want a thermostat to maintain. The user can optionally specify the duration for the new temperature setting.

The following examples show user utterances:

Alexa, set bedroom thermostat to twenty.
Alexa, set living room air conditioner to seventy-five.
Alexa, set the kitchen AC to twenty-five degrees for four hours.

SetTargetTemperature directive payload details

Field Description Type
targetSetpoint The thermostat should maintain the temperature at this setpoint. This field is included for single- and triple-setpoint thermostats. A temperature object.
lowerSetpoint The thermostat should maintain the temperature above this setpoint. This field is included for dual- and triple-setpoint thermostats. A temperature object.
upperSetpoint The thermostat should maintain the temperature below this setpoint. This field is included for dual- and triple-setpoint thermostats. A temperature object.
schedule The duration of time for which the thermostat should maintain the specified setpoints. Apply the new setpoints immediately, for the duration specified. This field is only included if the user specifies it, and you indicated that you support it in your discovery response. Currently, users can't request to set a temperature for a time in the future. A timeInterval object.

SetTargetTemperature directive example (single-setpoint thermostat)


{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      }
    }
  }
}

SetTargetTemperature directive example (single-setpoint thermostat with a schedule)

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 21.0,
        "scale": "CELSIUS"
      },
      "schedule": {
        "start": "2017-06-22T21:35Z",
        "duration": "PT25M"
      }
    }
  }
}

SetTargetTemperature directive example (dual-setpoint thermostat)

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 72.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

SetTargetTemperature response event

If you handle a SetTargetTemperature directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

SetTargetTemperature response event example (single-setpoint thermostat)

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.3,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

SetTargetTemperature response event example (dual-setpoint thermostat)

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "lowerSetpoint",
        "value": {
          "value": 68.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "upperSetpoint",
        "value": {
          "value": 72.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 66.5,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

SetTargetTemperature directive error handling

If you can't handle a SetTargetTemperature directive successfully, respond with an Alexa.ThermostatControllor.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error is not specific to temperature or thermostats.

AdjustTargetTemperature directive

Support the AdjustTargetTemperature directive so that users can adjust the temperature that they want a thermostat to maintain.

The following examples show user utterances:

Alexa, make it warmer in here.
Alexa, make it cooler in here.

AdjustTargetTemperature directive payload details

Field Description Type
targetSetpointDelta The amount by which to change the temperature. The amount can be positive or negative. A temperature object.

AdjustTargetTemperature directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": -2.0,
        "scale": "CELSIUS"
      }
    }
  }
}

AdjustTargetTemperature response event

If you handle an AdjustTargetTemperature directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

AdjustTargetTemperature response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

AdjustTargetTemperature directive error handling

If you can't handle a AdjustTargetTemperature directive successfully, respond with an Alexa.ThermostatControllor.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error is not 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 user thermostat device name to available mode.

The following examples show user utterances:

Alexa, set living room thermostat to automatic.

SetThermostatMode directive payload details

Field Description Type
thermostatMode The mode to set for the thermostat. A thermostatMode object.

SetThermostatMode directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

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.

SetThermostatMode response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 17.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

SetThermostatMode directive error handling

If you can't handle a SetThermostatMode directive successfully, respond with an Alexa.ThermostatControllor.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error is not specific to temperature or thermostats.

ResumeSchedule directive

Support the ResumeSchedule directive so that users can resume the programmed schedule of their thermostat after they previously overrode it. For example, a user might use the vacation override when they go away, and resume the normal program when they return.

The following examples show user utterances:

Alexa, resume living room thermostat schedule.

ResumeSchedule directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ResumeSchedule",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {}
  }
}

ResumeSchedule response event

If you handle a ResumeSchedule directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

ResumeSchedule response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 17.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

ResumeSchedule directive error handling

If you can't handle a ResumeSchedule directive successfully, respond with an Alexa.ThermostatControllor.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error is not 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 more information about state reports, see Understand State Reporting.

StateReport response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

StateReport response event example for an air conditioner

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      } 
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For more information about change reports, see Understand State Reporting.

ChangeReport event example

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController",
            "name": "thermostatMode",
            "value": "COOL",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.TemperatureSensor",
            "name": "temperature",
            "value": {
              "value": 19.1,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 1000
          } 
        ]
      }
    }
  },
  "context": {}
}

ChangeReport event example for an air conditioner

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController",
            "name": "thermostatMode",
            "value": "COOL",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          } 
        ]
      }
    }
  },
  "context": {}
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment