From 9e5236ffdac50dbdb0c5b8bed4b252b47b7b3325 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Tue, 14 Jul 2020 17:15:59 +0200
Subject: [PATCH] MQTT birth and will messages are published by default
 (#13931)

---
 source/_docs/mqtt/birth_will.markdown | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/source/_docs/mqtt/birth_will.markdown b/source/_docs/mqtt/birth_will.markdown
index 3c1737f3a91..7b4f136b2ce 100644
--- a/source/_docs/mqtt/birth_will.markdown
+++ b/source/_docs/mqtt/birth_will.markdown
@@ -4,9 +4,11 @@ description: "Instructions on how to setup MQTT birth and last will messages wit
 logo: mqtt.png
 ---
 
-MQTT supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about an ungracefully disconnected client.
+Home Assistant's MQTT integration supports so-called Birth and Last Will and Testament (LWT) messages. The former is used to send a message after the service has started, and the latter is used to notify other clients about a disconnected client. Please note that the LWT message will be sent both in case of a clean (e.g. Home Asisstant shutting down) and in case of an unclean (e.g. Home Assistant crashing or losing its network connection) disconnect.
 
-To integrate MQTT Birth and Last Will messages into Home Assistant, add the following section to your `configuration.yaml` file:
+By default, Home Assistant sends `online` and `offline` to `homeassistant/status`.
+
+To customize the MQTT Birth and Last Will messages, add the following section to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
@@ -26,12 +28,14 @@ birth_message:
   type: list
   keys:
     topic:
-      description: The MQTT topic to publish the message.
-      required: true
+      description: The MQTT topic to publish the message. Set to the empty string, `""`, to disable publishing a birth message.
+      required: false
+      default: homeassistant/status
       type: string
     payload:
       description: The message content.
-      required: true
+      required: false
+      default: online
       type: string
     qos:
       description: The maximum QoS level of the topic.
@@ -44,17 +48,19 @@ birth_message:
       default: false
       type: boolean
 will_message:
-  description: Will Message
+  description: Will Message. Set to the empty string, `""`, to disable publishing a will message.
   required: false
   type: list
   keys:
     topic:
       description: The MQTT topic to publish the message.
-      required: true
+      required: false
+      default: homeassistant/status
       type: string
     payload:
       description: The message content.
-      required: true
+      required: false
+      default: offline
       type: string
     qos:
       description: The maximum QoS level of the topic.