Alexa.AutomationManagement Interface 1.0

Implement the Alexa.AutomationManagement interface in your Alexa skill for your devices that support automation, such as thermostats. The AutomationManagement interface is intended to help users manage their energy usage with the Alexa energy dashboard. For details, see Smart Home Energy Overview.

If your device is a thermostat, you can control the automation of the thermostat. Alternatively, the user can ask Alexa to automate the thermostat by using hunches, in which case Alexa is controlling the automation of the thermostat. For details about hunches, see What Are Alexa Hunches? and Enable Alexa to Proactively Act on Hunches Without Customers Needing to Ask.

Only one entity should control the automation for a device at a time. When you implement the AutomationManagement interface, Alexa notifies you when the user wants Alexa to automate their device, and you notify Alexa when the user wants you to automate their device.

For the list of locales that the AutomationManagement interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Considerations and prerequisites

Before you use Alexa.AutomationManagement in your Alexa skill, consider the following:

Utterances

The AutomationManagement interface is different than other Alexa interfaces in that you aren't directly supporting voice user interactions with Alexa. Instead, you are communicating with Alexa about device automation. There are no user utterances associated with this interface.

Properties and Objects

The automationStatuses property

The Alexa.AutomationManagement interface uses the automationStatuses property to identify whether the user is automating their device through your skill or app. You send your automationStatuses to Alexa in your response to the UpdateAlexaAutomationStatus directive, state reports, and change reports.

The value of the automationStatuses property is an array of objects as explained following.

AutomationStatuses property value details

Field Description Type
status AUTOMATED if you are automating the interface, NOT_AUTOMATED if you aren't automating the interface. String
capability The name of the interface. You identify the interfaces that you support for automation in your discovery response. String

AutomationStatuses property example for ThermostatController

Copied to clipboard.

{
  "namespace": "Alexa.AutomationManagement",
  "name": "automationStatuses",
  "value": [
    {
      "status" : "AUTOMATED",
      "capability": "Alexa.ThermostatController"
    }
  ]
}

Discovery

You describe endpoints that support Alexa.AutomationManagement 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.

For the full list of display categories, see display categories.

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

Field Description Type
supportedAutomationCapabilities An array of interfaces that contain properties that the device can automate. Array

Discover response example for ThermostatController

The following example illustrates a Discover.Response for a thermostat that supports the Alexa.AutomationManagement, Alexa.ThermostatController, Alexa.TemperatureSensor, and Alexa.EndpointHealth interfaces. In this example, the thermostat supports automation for the Alexa.ThermostatController.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Smart Thermostat by Thermostat Maker",
          "friendlyName": "Hallway Thermostat",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "temperature"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3.1",
              "properties": {
                "supported": [
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedModes": [ "HEAT", "COOL", "AUTO" ],
                "supportsScheduling": false
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.AutomationManagement",
              "version": "1.0",
              "properties": {
                "supported": [
                  {
                    "name": "automationStatuses"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedAutomationCapabilities": [
                  {
                    "capability" : "Alexa.ThermostatController"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

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

UpdateAlexaAutomationStatus directive

Support the UpdateAlexaAutomationStatus directive so that Alexa can notify you of whether the user is automating their device through Alexa. Alexa also sends the UpdateAlexaAutomationStatus directive after you send a GetAlexaAutomationStatus event.

When Alexa sends you a status of AUTOMATED, change your own status to NOT_AUTOMATED.

UpdateAlexaAutomationStatus directive example

The following example illustrates a UpdateAlexaAutomationStatus directive that Alexa sends to your skill. In this example, Alexa is automating the user's thermostat.

{
  "directive": {
    "header": {
      "namespace": "Alexa.AutomationManagement",
      "name": "UpdateAlexaAutomationStatus",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "1.0"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "alexaAutomationStatuses": [
        {
          "status" : "AUTOMATED",
          "capability": "Alexa.ThermostatController"
        }
      ]
    }
  }
}

UpdateAlexaAutomationStatus directive payload

Field Description Type
alexaAutomationStatuses Identifies whether the user is automating their device through Alexa. An array of alexaAutomationStatus objects as explained following.
alexaAutomationStatus.
status		 AUTOMATED if Alexa is automating the interface, NOT_AUTOMATED if Alexa isn't automating the interface. String
alexaAutomationStatus.
capability		 The name of the interface. You identify the interfaces that you support for automation in your discovery response. String

UpdateAlexaAutomationStatus response

If you handle a UpdateAlexaAutomationStatus directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.

In the context object, specify the current value for your automationStatuses.

The following example illustrates your response to the UpdateAlexaAutomationStatus directive for a thermostat. In this example, Alexa is automating the user's device so your status is NOT_AUTOMATED.

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": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.AutomationManagement",
        "name": "automationStatuses",
        "value": [
          {
            "status" : "NOT_AUTOMATED",
            "capability": "Alexa.ThermostatController"
          }
        ],
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

UpdateAlexaAutomationStatus directive error handling

If you can't handle a UpdateAlexaAutomationStatus directive successfully, respond with an Alexa.ErrorResponse event.

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. For details about state reports, see Understand State Reporting.

The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response.

StateReport event for ThermostatController example

The following example illustrates a state report for a thermostat that supports the Alexa.AutomationManagement, Alexa.ThermostatController, Alexa.TemperatureSensor, and Alexa.EndpointHealth interfaces. In this example, Alexa is automating the user's device so your status is NOT_AUTOMATED.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-02-03T16:15:10.00Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2024-02-01T08:15:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-02-01T08:15:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.AutomationManagement",
        "name": "automationStatuses",
        "value": [
          {
            "status" : "NOT_AUTOMATED",
            "capability": "Alexa.ThermostatController"
          }
        ],
        "timeOfSample": "2024-02-02T16:15:00.00Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2024-02-03T16:15:00.00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to report changes proactively in the state of an endpoint. For more details about change reports, see Understand State Reporting.

The ChangeReport contains the value of all properties that changed in the payload object. You identify the properties that you proactively report in your discovery response.

In the following examples, the user updates their preferences in your app and you want to resume automating their device instead of Alexa. Optionally, you can check first whether Alexa is automating the device by sending a GetAlexaAutomationStatus event, and ask the user to confirm that they want you to resume automating their device.

ChangeReport event example for ThermostatController

The following example illustrates a change report for a device that supports the Alexa.AutomationManagement, Alexa.ThermostatController, Alexa.TemperatureSensor, and Alexa.EndpointHealth interfaces. The user updates their preferences in your app and you want to resume automating their device instead of Alexa. Your automation status property has changed, so it appears in the payload, while the other properties haven't changed, so they appear in the context.

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": "APP_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.AutomationManagement",
            "name": "automationStatuses",
            "value": [
                {
                    "status": "AUTOMATED",
                    "capability": "Alexa.ThermostatController"
                }
            ],
            "timeOfSample": "2024-02-03T12:15:00.00Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-02-03T12:00:00.00Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2024-02-02T16:15:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-02-02T16:15:00.00Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2024-02-03T12:00:00.00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

GetAlexaAutomationStatus request

When you want to know whether Alexa is currently automating a device, you send a GetAlexaAutomationStatus event to the Alexa Event Gateway. After Alexa receives your event, Alexa sends an UpdateAlexaAutomationStatus directive to your skill that contains the current alexaAutomationStatuses.

For example, if the user updates their preferences in your app and you want to resume automating their device instead of Alexa, you can check first to see if Alexa is currently automating the device. If Alexa is automating the device, you can ask the user to confirm that they want you to resume automating their device.

GetAlexaAutomationStatus event example for ThermostatController

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.AutomationManagement",
      "name": "getAlexaAutomationStatus",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "1.0"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "Alexa.ThermostatController"
        }
      ]
    }
  },
  "context": {
  }
}
Was this page helpful?

Last updated: Aug 23, 2024