Alexa.DoorbellEventSource Interface 3

Implement the Alexa.DoorbellEventSource interface in your Alexa skill for devices that raise doorbell events. The customer selects which of their Echo devices respond to doorbell events. Alexa uses doorbell events for announcements, mobile notifications, routines, and other use cases. For more details about security skills, see Smart Home Security Overview.

When a doorbell event occurs, Alexa plays the doorbell announcement on the selected Echo devices. If the customer selected an Echo device without a screen, the Echo device plays the doorbell announcement. If the customer selected an Echo Show device and the doorbell implements the Alexa.RTCSessionController interface, the Echo Show device plays the doorbell announcement and automatically displays a live feed from the doorbell video camera when the doorbell event occurs.

For the list of languages that the Alexa.DoorbellEventSource 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.DoorbellEventSource interface doesn't have any user utterances.

Reportable properties

The Alexa.DoorbellEventSource doesn't define any reportable properties.

Discovery

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

Use DOORBELL for the display category. If your device is a video doorbell with a camera, use CAMERA and DOORBELL for the display categories. For the full list of display categories, see display categories.

To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Discover response example

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": "Sample Manufacturer",
                "description": "Description that appears in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app",
                "displayCategories": ["CAMERA", "DOORBELL"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.DoorbellEventSource",
                        "version": "3",
                        "proactivelyReported": true
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives and events

The Alexa.DoorbellEventSource interface doesn't define any directives.

DoorbellPress event

Send a DoorbellPress event to the Alexa event gateway whenever your device detects the doorbell press. For details, see Send Events to the Event Gateway.

When your skill reports a DoorbellPress event, you must wait at least 30 seconds before sending another DoorbellPress event for the same device.

DoorbellPress event example

The following example shows a DoorbellPress event.

Copied to clipboard.

{
    "context": { },
    "event": {
        "header": {
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "namespace" : "Alexa.DoorbellEventSource",
            "name": "DoorbellPress",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload" : {
            "cause": {
                "type": "PHYSICAL_INTERACTION"
            },
            "timestamp": "2018-06-09T23:23:23.23Z"
        }
    }
}

DoorbellPress event payload

Property Description Type Required

cause

Describes why this event occurred.

Cause object

Yes

timestamp

Time the endpoint detected the event.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

Change reporting

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.

Was this page helpful?

Last updated: Nov 22, 2023