Alexa.EventDetectionSensor Interface 3

Implement the Alexa.EventDetectionSensor interface in your Alexa skill so that you can notify Alexa when your security camera devices detect the presence of a person. When your security camera detects a person, you report that information to Alexa in a change report, and Alexa notifies your user. Users can set up notifications and routines for person detection in the Alexa app. By setting up person detection, users can reduce the number of notifications they receive when tracking all motion detection. For more details about security skills, see Smart Home Security Overview.

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

Utterances

The Alexa.EventDetectionSensor interface doesn't have any user utterances.

Reportable properties

The Alexa.EventDetectionSensor interface uses the humanPresenceDetectionState property as the primary property.

The following example shows the humanPresenceDetectionState object.

Copied to clipboard.

{
    "value": "DETECTED",
    "detectionMethods": ["VIDEO"]
}

The following table shows the definition of the humanPresenceDetectionState object.

Field Description Type Required
value Indicates whether the endpoint detects presence.
Valid values: DETECTED or NOT_DETECTED.
String Yes
detectionMethods Methods that the endpoint used to detect the event.
Valid values: AUDIO, VIDEO.
Default: [AUDIO, VIDEO].
Array No

Discovery

You describe endpoints that support Alexa.EventDetectionSensor using the standard discovery mechanism described in Alexa.Discovery.

Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use CAMERA for the display category. For the full list of display categories, see display categories.

Configuration object

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

Field Description Type Required
detectionMethods Methods that the endpoint uses to detect the event.
Valid values: AUDIO, VIDEO.
Default: [AUDIO, VIDEO].
Array of strings No
detectionModes Type of events that the endpoint detects. If you don't specify detectionModes, the default is humanPresence. Object No
detectionModes[].
humanPresence.
featureAvailability
Indicates whether the human presence detection feature is available.
Valid values: ENABLED, DISABLED, SUBSCRIPTION_REQUIRED
Default: ENABLED.
String No
detectionModes[].
humanPresence.
supportsNotDetected
Indicates whether the endpoint supports the NOT_DETECTED state.
Default: true.
Boolean No

Discover response example

The following example shows a Discover.Response message for a security camera that supports the Alexa.EventDetectionSensor and Alexa.EndpointHealth interfaces.

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": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["CAMERA"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EventDetectionSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "humanPresenceDetectionState"
                  }
                ],
                "retrievable": false,
                "proactivelyReported": true
              },
              "configuration": {
                "detectionMethods": ["AUDIO", "VIDEO"],
                "detectionModes": {
                  "humanPresence": {
                    "featureAvailability": "ENABLED",
                    "supportsNotDetected": false
                  }
                }
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

AddOrUpdateReport

You must proactively send an Alexa.Discovery.AddOrUpdateReport message if the feature support of your endpoint changes. For example, if human presence detection requires a subscription, your first discovery response indicates that the human presence detection feature is disabled. If the user buys a subscription, send an AddOrUpdateReport message to indicate that the human presence detection feature is now enabled. Also send an AddOrUpdateReport message if the user manually disables human presence detection. For more details, see AddOrUpdateReport.

AddOrUpdateReport event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "AddOrUpdateReport",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["CAMERA"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EventDetectionSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "humanPresenceDetectionState"
                  }
                ],
                "retrievable": false,
                "proactivelyReported": true
              },
              "configuration": {
                "detectionMethods": ["AUDIO", "VIDEO"],
                "detectionModes": {
                  "humanPresence": {
                    "featureAvailability": "DISABLED",
                    "supportsNotDetected": false
                  }
                }
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Change report

You send a ChangeReport event to report changes proactively 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 with person detected

The following example shows a change report that you send when you detect human presence.

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": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.EventDetectionSensor",
            "name": "humanPresenceDetectionState",
            "value": {
              "value": "DETECTED",
              "detectionMethods": ["VIDEO"]
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}