Alexa.DoorbellEventSource Interface

The Alexa.DoorbellEventSource interface describes an endpoint that is capable of raising doorbell events. The customer selects which of their Echo devices respond to doorbell events.

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.

Alexa uses doorbell events for announcements, mobile notifications, routines, and other use cases. For more information, see Announcing Doorbell Chime APIs.

For the list of locales that are supported for the DoorbellEventSource interface, see List of Capability Interfaces and Supported Locales.

Discovery

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

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

Discover response example

{
  "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": ["DOORBELL"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.DoorbellEventSource",
              "version": "3",
              "proactivelyReported" : true
            }
          ]
        }
      ]
    }
  }
}

DoorbellPress Event

Send a DoorbellPress event to the Alexa Event Gateway whenever the doorbell is pressed. For more information, see Send Events to the Event Gateway.

DoorbellPress event payload details

Field Description Type Required
cause Describes why this event occurred. A cause object Yes
timestamp When the activation event occurred, specified in UTC. A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. Yes

DoorbellPress event example

{
    "context": { },
    "event": {
        "header": {
            "messageId": "9eac4fa2-9de0-4e75-ac38-9dde79abb1bd",
            "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"
        }
    }
}