Alexa.ContactSensor Interface

The Alexa.ContactSensor interface describes the properties and events used to report the state of an endpoint that detects contact between two surfaces. For example, a contact sensor can report whether a door or window is open.

A contact sensor typically has two components; a main component and a magnet component. When the components are in contact with each other, the sensor is closed. When they lose contact, the sensor is open.

The following image shows the open and closed states of a contact sensor on a window.

Discovery

You describe endpoints that supports Alexa.ContactSensor using the standard discovery mechanism described in Alexa.Discovery. For an example discovery response message for sensors, see the discovery example on the Build Smart Home Skills for Sensors page.

Directives

This interface does not define any directives, but sends change reports when a capability property changes and optionally responds to Alexa's requests for the state of the endpoint.

ReportState

A ReportState directive is sent to request the state of an endpoint.

Example ReportState Request

The following example shows a request for the current state of an endpoint with the ID appliance-001.

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

Properties and events

For this interface, you can reply:

  • Synchronously with a StateReport directive from the skill's Lambda function.
  • Asynchronously, which means you send StateReport events 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.

Properties

Property Name Type Description
detectionState Detection object Indicates the contact sensor state.

DETECTED means the sensor is open and the two pieces of the sensor are not in contact with each other. For example, a window has been opened.

NOT_DETECTED means the sensor is closed and the two pieces of the sensor are in contact with each other.

StateReport event

Use a StateReport event to report the value of all of the endpoint properties in response to a ReportState directive.

Example: StateReport

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ContactSensor",
        "name": "detectionState",
        "value": "DETECTED",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "StateReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

ChangeReport event

Use a ChangeReport event to report when the value of one of the endpoint properties changes for any reason. Report additional unchanged property values in the context of the message. Send ChangeReport events to the Alexa event gateway. For more information about how to do this, see Send Events to the Event Gateway.

If the device is low-power and unable to respond to ReportState requests, you must send a ChangeReport event immediately after discovery so the Alexa app can reflect the correct state of the endpoint. Subsequent change reports should be sent only when a change is detected.

Example: ChangeReport

{
  "context": {},
  "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.ContactSensor",
            "name": "detectionState",
            "value": "DETECTED",
            "timeOfSample": "2018-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Alexa.MotionSensor
Describes an endpoint that senses motion.
Build Smart Home Skills for Sensors
Describes considerations for building a smart home skill that supports sensors.