Alexa.ThermostatController Interface

Implement the Alexa.ThermostatController interface in your Alexa skill so that users can control smart thermostats. A thermostat can control devices such as furnaces, air conditioners, ceiling fans, and water heaters. For details about Smart Home skills, see Understand the Smart Home Skill API.

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 in conjunction with the Alexa.TemperatureSensor interface.

To enable Alexa to estimate the energy use of a thermostat device or HVAC system, implement the Alexa.ThermostatController.HVAC.Components interface.

For the list of languages that the ThermostatController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.ThermostatController interface, the 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.
Alexa, what mode is my thermostat set to?

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

Thermostat setpoint types

Alexa supports thermostats with one or two setpoints.

Single-setpoint thermostats
A single-setpoint thermostat has a single temperature setting that it attempts to maintain. For example, a thermostat with a single setpoint might turn on 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.

A thermostat can support different setpoints when in different modes. For details, 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.

Properties

The Alexa.ThermostatController interface defines the following properties.

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 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 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, and that doesn't support scheduling.

Copied to clipboard.

{
  "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": "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 Alexa skill that controls an air conditioner and supports the ThermostatController and PowerController interfaces. You don't need to implement the Alexa.TemperatureSensor interface unless your air conditioner displays the temperature.

Copied to clipboard.

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

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. The directive includes this field for single-setpoint thermostats. A temperature object.
lowerSetpoint The thermostat should maintain the temperature above this setpoint. The directive includes this field for dual-setpoint thermostats. A temperature object.
upperSetpoint The thermostat should maintain the temperature below this setpoint. The directive includes this field for dual-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)

The following example illustrates a SetTargetTemperature directive that Alexa sends to your skill.


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

The following example illustrates a SetTargetTemperature directive that Alexa sends to your skill and requests 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)

The following example illustrates a SetTargetTemperature directive that Alexa sends to your skill for a 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)

Copied to clipboard.

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

Copied to clipboard.

{
  "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.ThermostatController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to temperature or thermostats.

AdjustTargetTemperature directive

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

The following examples show user utterances:

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

AdjustTargetTemperature directive 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

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

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

Copied to clipboard.

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

The following example illustrates a SetThermostatMode directive that Alexa sends to your skill.

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

Copied to clipboard.

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

The following example illustrates a ResumeSchedule directive that Alexa sends to your skill.

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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

{
  "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 details about change reports, see Understand State and Change Reporting.

ChangeReport event example

Copied to clipboard.

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

Copied to clipboard.

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

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