From a49d80119ad67948911624f1bca135af6c658683 Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Sun, 23 Jul 2023 20:16:53 +0200
Subject: [PATCH] Alexa doorbell event via event entity (#28291)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
---
 .../_integrations/alexa.smart_home.markdown   | 43 +++++++++++++------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/source/_integrations/alexa.smart_home.markdown b/source/_integrations/alexa.smart_home.markdown
index 394983d3fc7..516b5ba5085 100644
--- a/source/_integrations/alexa.smart_home.markdown
+++ b/source/_integrations/alexa.smart_home.markdown
@@ -49,7 +49,7 @@ Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant:
     - [Routines](#routines)
   - [Button, Input Button](#button-input-button)
     - [Routines](#routines-1)
-    - [Doorbell Announcement](#doorbell-announcement)
+    - [Doorbell Announcement with binary\_sensor](#doorbell-announcement-with-binary_sensor)
     - [Presence Detection with Binary Sensor](#presence-detection-with-binary-sensor)
   - [Camera](#camera)
   - [Climate](#climate)
@@ -60,6 +60,8 @@ Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant:
     - [Set Cover Position](#set-cover-position)
     - [Set Cover Tilt](#set-cover-tilt)
     - [Garage Doors](#garage-doors)
+  - [Event entities](#event-entities)
+    - [Doorbell Events](#doorbell-events)
   - [Fan](#fan)
     - [Fan Speed](#fan-speed)
     - [Fan Preset Mode](#fan-preset-mode)
@@ -437,7 +439,7 @@ light.kitchen_light:
 ```
 
 <div class='note info'>
-Devices such as cameras, doorbells, garage doors, and alarm control panels require specific display categories to provide all available features from Amazon Alexa. Overriding the default display category will limit features provided by Amazon Alexa.
+Devices such as cameras, garage doors, and alarm control panels require specific display categories to provide all available features from Amazon Alexa. Overriding the default display category will limit features provided by Amazon Alexa.
 </div>
 
 See [Alexa Display Categories][alexa-display-categories] for a complete list
@@ -466,7 +468,7 @@ The following integrations are currently supported:
     - [Routines](#routines)
   - [Button, Input Button](#button-input-button)
     - [Routines](#routines-1)
-    - [Doorbell Announcement](#doorbell-announcement)
+    - [Doorbell Announcement with binary\_sensor](#doorbell-announcement-with-binary_sensor)
     - [Presence Detection with Binary Sensor](#presence-detection-with-binary-sensor)
   - [Camera](#camera)
   - [Climate](#climate)
@@ -477,6 +479,8 @@ The following integrations are currently supported:
     - [Set Cover Position](#set-cover-position)
     - [Set Cover Tilt](#set-cover-tilt)
     - [Garage Doors](#garage-doors)
+  - [Event entities](#event-entities)
+    - [Doorbell Events](#doorbell-events)
   - [Fan](#fan)
     - [Fan Speed](#fan-speed)
     - [Fan Preset Mode](#fan-preset-mode)
@@ -601,11 +605,13 @@ In order to enable this, buttons will appear to have "presence detection" capabi
   <img height='460' src='/images/integrations/alexa/alexa_app_button_trigger.png' alt='Screenshot: Alexa App Button Routine Trigger'/></a>
 </p>
 
-#### Doorbell Announcement
+#### Doorbell Announcement with binary_sensor
 
 Requires [Proactive Events](#proactive-events) enabled.
 
-Configure a `binary_sensor` with `display_category` of `DOORBELL` in the [`entity_config`](#entity_config) to gain access to the doorbell notification settings in the Alexa App.
+Note that Home Assistant can support a doorbell natively with an `event` entity with `device_class` to `doorbell`
+
+Configure a `binary_sensor` with `display_category` of `DOORBELL` in the [`entity_config`](#entity_config) to gain access to the doorbell notification settings in the Alexa App. Note that Home Assistant can support this natively with an `event` entity.
 
 ```yaml
 alexa:
@@ -619,14 +625,7 @@ alexa:
 
 Alexa will announce on all echo devices _"Someone is at the [entity name]"_ when a `binary_sensor` state changes from `off` to `on`.
 
-<div class='note info'>
-Each Amazon Echo device will need the communication and announcements setting enabled, and the Do Not Disturb feature turned off.
-</div>
-
-<p class='img'>
-<a href='/images/integrations/alexa/alexa_app_doorbell_announcement.png' target='_blank'>
-  <img height='460' src='/images/integrations/alexa/alexa_app_doorbell_announcement.png' alt='Screenshot: Alexa App Doorbell Notification'/></a>
-</p>
+See also [Event entities](#event-entities).
 
 #### Presence Detection with Binary Sensor
 
@@ -770,6 +769,24 @@ Covers with a `device_class` of `garage` support the Open by Voice PIN feature i
   <img height='460' src='/images/integrations/alexa/alexa_app_garage_door_pin.png' alt='Screenshot: Alexa App Garage Door Open by voice'/></a>
 </p>
 
+### Event entities
+
+Requires [Proactive Events](#proactive-events) enabled.
+
+#### Doorbell Events
+
+Home Assistant `event` entities can trigger a doorbell announcement in Alexa if the `device_class` of the `event` entity is set to `doorbell`.
+Alexa will announce on all echo devices _"Someone is at the [entity name]"_ when an `event` entity has received an updated.
+
+<div class='note info'>
+Each Amazon Echo device will need the communication and announcements setting enabled and the Do Not Disturb feature turned off.
+</div>
+
+<p class='img'>
+<a href='/images/integrations/alexa/alexa_app_doorbell_announcement.png' target='_blank'>
+  <img height='460' src='/images/integrations/alexa/alexa_app_doorbell_announcement.png' alt='Screenshot: Alexa App Doorbell Notification'/></a>
+</p>
+
 ### Fan
 
 Control fan speed, direction, and oscillation.