How to use the Doorbell Event Source for Alexa Devices

There is a notification capability available for amazon echo devices called Alexa.DoorbellEventSource which can be used to integrate door bells. A door bell device can push notifications to echo devices, so you will be notified by voice when someone rings at the door.

If you want to implement your own door bell events (or other push notifications), you need a SmartHome Skill with account linking enabled, lambda functions, a database to store credentials and tokens, alexa echo devices and of course a door bell that can send either a POST request to an API-Gateway or an MQTT message to IoT core.

I assume you already have a working SmartHome Skill. Make sure you have set up account linking, because this is required to use the Alexa Event Gateway, not just for doorbell events but also for other push notifications. Detailed instructions to configure account linking can be found here, read through steps 2 to 5, but skip the API-GW deployment parts.

Setup a doorbell device definition

To configure the doorbell device In your SmartHome lambda function you must add a new device with the DoorbellEventSource capability to the device discovery event response:

After device discovery by alexa, open the doorbell device in the alexa app and enable announcements for the doorbell press event!

Account linking

Since we need account linking to get the credentials to push events to the Event Gateway, you must also add a handler in your SmartHome skill lambda function to handle authorization requests. This will be triggered when you enable the skill in the app and log in using LWA (Login with amazon). If your SmartHome skill is already enabled, just disable and re-enable again to force the login.

The AcceptGrant event contains a token which identifies the user and an authentication code which can be used to request bearer tokens to communicate on behalf of the user with the Alexa Event Gateway. Use payload.grantee.token to identify the user and create a user profile in your database.

Get bearer tokens

Next step is to request a bearer token by sending the payload.grant.code from the AcceptGrant event above to the auth API.

Save the received credentials to the user profile in your database (e.g. DynamoDB) and also the timestamp, so you know when the access token expires and needs to be refreshed using the refresh token. Those credentials are needed every time you communicate with the Alexa Event Gateway.

Send event to the event gateway

Finally we have a valid bearer token to send events on behalf of the end-user. We can now send a DoorBell event to the Alexa Event Gateway while the token is valid. When the token has expired, you should proactively refresh the token first, before sending the event to the gateway, or you will get a status 400 response.

POST request to the event gateway to trigger the doorbell interaction:

On success you will just receive a status code 202 without any request body and the event should be announced on your alexa echo devices! Make sure you have enabled announcements in the doorbell device settings in the alexa app!

If your bearer token has expired, you will receive a status 400 and you have to refresh the bearer token first by sending the refresh token (stored in the user profile database) to the authentication API:

You have to store the renewed credentials again in your user profile database and then send the DoorBell event again to the event gateway using the renewed bearer token.

To actually trigger the procedure to deliver the DoorBell event as described above, you can put all this into a Lambda function and expose the lambda either via API-Gateway or set up a trigger in the IoT Hub console and listen for a specific topic to invoke the lambda function.