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
  • French (FR)
  • German
  • Italian
  • Japanese
  • Spanish (ES)

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. For more information about state reporting, see State Reporting in a Smart Home Skill.

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

Properties

The Alexa interface does not currently define any reportable properties.

ChangeReport

ChangeReport events are sent to notify Alexa of state changes. You specify a property as proactivelyReported during discovery, and then you send Alexa a ChangeReport event whenever that property value changes, regardless of why the property changed. For example, if the "Kitchen Light" endpoint turns on, you would notify Alexa by sending a ChangeReport event that indicates the powerState property of the Alexa.PowerController interface has changed its value to "ON".

  • Use the payload of the ChangeReport to provide the new property value and the reason for the change.
  • You use the context of a ChangeReport to report the state of any additional 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.

For more information about change reports and state reporting, see State Reporting in a Smart Home Skill.

You must send change reports 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.


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
  "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" :  "endpoint-001" ,
    },
    "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. For more information, see property object and cause object.

DeferredResponse

Use a DeferredResponse to respond synchronously to a directive that you plan to later send a delayed or asynchronous response. After you send a DeferredResponse, you should later send a Response event.

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

Example DeferredResponse


{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "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": "abc-123-def-456",
      "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 must report the value of affected properties in the context of the message, but you can include any and all reportable properties in the context.

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": "abc-123-def-456",
            "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.


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
    "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": "abc-123-def-456",
            "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 from your skill's Lambda function.
  • Asynchronously, 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.

For more information about state reporting, see State Reporting in a Smart Home Skill.

Example State Report Response

In this synchronous 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":{  
         "endpointId":"appliance-001",
         "cookie":{}
      },
      "payload":{  
      }
   }
}

Additional Sample Code

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