Alexa.EventDetectionSensor Interface
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 information about security skills, see Smart Home Security Overview.
You can also support the Alexa.MediaMetadata Interface to enable Alexa to search and display the media clip of the person that is detected. Users can ask Alexa questions like "Alexa, show the last person detected at my front door."
For the list of languages that the EventDetectionSensor interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
When you use the Alexa.EventDetectionSensor and Alexa.MediaMetadata interfaces, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, show me the last time someone was at the front door.
Alexa, show me the last time a person was detected at the front door.
Alexa, show me the last person detected at the front door.
Alexa, show me the most recent person at the front door.
After the customer says one of these utterances, Alexa displays the media clip identified in the most recent change report sent by your skill.
Properties
The Alexa.EventDetectionSensor interface uses the humanPresenceDetectionState property as the primary property.
HumanPresenceDetectionState property details
| Field | Description | Type | Required |
|---|---|---|---|
value |
Whether presence is detected or not. Valid values are DETECTED or NOT_DETECTED. |
String | Yes |
detectionMethods |
The methods that the endpoint used to detect the event. Valid values are AUDIO, VIDEO. |
Array | No |
media |
The identifier of the audio or video recorded for the detection event. | Object | No |
HumanPresenceDetectionState property example
{
"value": "DETECTED",
"detectionMethods": ["VIDEO"],
"media": {
"type": "ALEXA.MEDIAMETADATA",
"id": "<media metadata id>"
}
}
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.
In addition to the usual discovery response fields, for EventDetectionSensor, include a configuration object that contains the following fields.
| Field | Description | Type | Required |
|---|---|---|---|
detectionMethods |
The methods that the endpoint uses to detect events; AUDIO, VIDEO. The default value is ["AUDIO", "VIDEO"]. |
Array | No |
detectionModes |
The types of events that the endpoint detects. If you don't specify detectionModes, the default is humanPresence. |
Array | No |
detectionModes.humanPresence.featureAvailability |
Indicates whether the human presence detection feature is available. The default value is ENABLED. |
A feature availability value. | No |
detectionModes.humanPresence.supportsNotDetected |
Indicates whether the endpoint supports the NOT_DETECTED state. The default value is true. |
Boolean | No |
Discover response example
The following example shows a Discover.Response message for a security camera that supports Alexa.EventDetectionSensor and Alexa.MediaMetadata.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is 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.MediaMetadata",
"version": "3",
"proactivelyReported": true
},
{
"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 information, see AddOrUpdateReport.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is 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.MediaMetadata",
"version": "3",
"proactivelyReported": true
},
{
"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 proactively report changes 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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.EventDetectionSensor",
"name": "humanPresenceDetectionState",
"value": {
"value": "DETECTED",
"detectionMethods": ["VIDEO"],
"media": {
"type": "ALEXA.MEDIAMETADATA",
"id": "<media metadata id>"
}
},
"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
}
]
}
}