Your Alexa Dashboards Settings

Alexa Interface

The Alexa interface contains directives and events related to state and error reporting. Although endpoints implement this interface implicitly, you should explicitly include this interface and the supported version in your discovery response.

Discovery

The following example shows how to identify this interface in your discovery response.

. . .
    {
    "type": "AlexaInterface",
    "interface": "Alexa",
    "version": "3"
    }
. . .

Directives

The control and query directives in this interface are supported in skills that target the following languages:

  • English - all locales
  • German
  • Japanese

See Develop Smart Home Skills in Multiple Languages for more information.

ReportState

A ReportState directive is sent to request the current values of state properties for an endpoint. The endpoint appliance-001 in this case, is specified in the message. You respond to a ReportState with a StateReport and include all of the properties you have defined for that endpoint.

Example ReportState Request

{
  "directive": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "ReportState",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {},
      "scope":{  
            "type":"BearerToken",
            "token":"access-token-from-skill"
      }
    },
    "payload": {
    }
  }
}

Events and Properties

Reportable Properties

The Alexa interface does not currently define any reportable properties.

ChangeReport

ChangeReport events are sent to proactively notify Alexa of state changes and ensure the Alexa app reflects current device state. For example, a customer manually switches on the “Kitchen Light” endpoint, and you notify Alexa by sending a ChangeReport event that indicates the powerState property of the Alexa.PowerController interface has changed its value to “ON”.

If a property is specified as proactivelyReported during discovery, you must send Alexa a ChangeReport event whenever that property value changes as the cause is not a directive request from Alexa.

  • Use the payload of the ChangeReport to provide the new property value and the reason for the change.
  • You can optionally use the context of a ChangeReport to report the state of any additional properties, if you think they may have changed, or would like to report the current state of all the properties.
  • If multiple properties have changed, you can send Alexa multiple change report events containing a payload with a single property, or a single change report event that contains a payload with multiple property values.
  • Make sure to identify the customer and the endpoint for the change report in the endpoint object.

Because you send change reports proactively, and not as the result of a customer voice interaction with Alexa, you must send them to the event gateway. This requires that you request permission to send events to this endpoint and store authentication information for each customer, which you include in the change report scope. For more information, see Authenticate a Customer to Alexa with Permissions.

In the following example, the ChangeReport event is for an endpoint that implements the Alexa.PowerController and Alexa.BrightnessController interfaces. The event reports that the endpoint changed its powerState from “OFF” to “ON” due to a physical interaction with the device and reports the brightness in the context object, because the brightness level did not change.

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.BrightnessController",
        "name": "brightness",
        "value": 85,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 60000
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type":"BearerToken",
        "token":"access-token-from-Amazon"
       },
       "endpointId" :  "<the endpoint identifier of the endpoint >" ,
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Payload details

The payload of a ChangeReport event specifies a change object that contains an array of changed properties and a cause object that specifies a reason for the change.

Field Description Type Required
change Specifies the cause of the change An object that contains a cause object yes
properties Contains an array of property objects that caused the change report to be sent. array of property objects yes
*property*.namespace The namespace of the changed property string yes
*property*.name The name of the changed property string yes
*property*.value The current value of the changed property varies depending on property type yes
*property*.timeOfSample The time the property changed string in ISO 8601 format, Zulu time. yes
*property*.uncertaintyInMilliseconds Number of milliseconds the property value could be string yes

Cause Object

The cause attribute is used to describe the cause of a property value change when you send a ChangeReport event. It is a polymorphic type with the following descendant types:

Cause Type Description
APP_INTERACTION Indicates that the event was caused by a customer interaction with an application. For example, a customer switches on a light, or locks a door using the Alexa app or an app provided by a device vendor.
PHYSICAL_INTERACTION Indicates that the event was caused by a physical interaction with an endpoint. For example manually switching on a light or manually locking a door lock
PERIODIC_POLL Indicates that the event was caused by the periodic poll of an appliance, which found a change in value. For example, you might poll a temperature sensor every hour, and send the updated temperature to Alexa.
RULE_TRIGGER Indicates that the event was caused by the application of a device rule. For example, a customer configures a rule to switch on a light if a motion sensor detects motion. In this case, Alexa receives an event from the motion sensor, and another event from the light to indicate that its state change was caused by the rule.
VOICE_INTERACTION Indicates that the event was caused by a voice interaction with Alexa. For example a user speaking to their Echo device.

DeferredResponse

Use a DeferredResponse to respond synchronously to a directive that you plan to later send an asynchronous response for. After you send a DeferredResponse, you should send an Response event later to the Alexa event gateway.

Because you always send a DeferredResponse synchronously, it does not include a scope.

Example DeferredResponse

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "954fad82-15b4-4367-9e6a-297926031855",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

Payload details

Field Description Type Required
estimatedDeferralInSeconds Optional. An integer that indicates an approximate time, in seconds, before the asynchronous response is sent. integer no

When you receive a directive, you can send a synchronous response or a DeferredResponse indicating you received the directive, and later follow up with an asynchronous event to the Alexa endpoint. In either case, there is a hard limit of 8 seconds before Alexa times out.

Known exceptions to the 8 second limit are:

Capability Interface Notes
LockController With slower locks, specify the expected deferral of the Response with the estimatedDeferralInSeconds in the DeferredResponse.

ErrorResponse

Send an ErrorResponse if you cannot process a directive as expected. For a list of error types and more examples, see the Alexa.ErrorResponse topic.

Following is an example error response.

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"access-token-from-Amazon"
       },
       "endpointId":"appliance-001"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "Unable to reach endpoint 12345 because it appears to be offline"
    }
  }
}

Response

If a directive is successfully handled, you should respond with an Response event. A Response can be sent from a Lambda function to Alexa or from your device cloud to the Alexa event gateway. When you send a response event you should report the value of affected properties in the context of the message.

In most cases Alexa waits 8 seconds before timing out whether the response is synchronous or asynchronous. Exceptions are noted in individual interfaces. For example, Alexa will wait longer for an asynchronous response from an endpoint that implements the LockController interface.

If you are responding asynchronously to the event gateway, the Response must include a scope that authenticates the customer to Alexa. When you respond synchronously or asynchronously, the message should include a correlation token.

Synchronous Response example

The following example shows a synchronous response for a endpoint that supports tunable white light.

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

Asynchronous Response example

The following example shows a asynchronous response for a endpoint that supports tunable white light.

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

StateReport

The expected reply to a ReportState directive is a StateReport, event which must include a context object that contains all of the reportable properties identified during the discovery process for each capability interface implemented by the endpoint. You should report the current value of the properties. If you don’t know the state of the properties, because the endpoint is offline or unreachable, you should return an ErrorResponse specifying the issue.

When you send a StateReport you can send it:

  • Synchronously as a reply to a ReportState directive.
  • Asynchronously, with a StateReport event to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

Example State Report Response

In this example, the endpoint implements the Alexa.ThermostatController capability interface.

{  
   "context":{  
      "properties":[  
         {  
            "namespace":"Alexa.ThermostatController",
            "name":"targetSetpoint",
            "value":{  
               "value":25.0,
               "scale":"CELSIUS"
            },
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds":6000
         },
         {  
            "namespace":"Alexa.ThermostatController",
            "name":"thermostatMode",
            "value":"HEAT",
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds":6000
         }
      ]
   },
   "event":{  
      "header":{  
         "messageId":"abc-123-def-456",
         "correlationToken":"abcdef-123456",
         "namespace":"Alexa",
         "name":"StateReport",
         "payloadVersion":"3"
      },
      "endpoint":{  
         "scope":{  
            "type":"BearerToken",
            "token":"access-token-from-skill"
         },
         "endpointId":"appliance-001",
         "cookie":{  

         }
      },
      "payload":{  

      }
   }
}

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo: