diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index 45f452f5a88..6c79aa48fa8 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -22,7 +22,7 @@ To enable Jabber notifications in your installation, add the following to your ` ```yaml # Example configuration.yaml entry notify: - - name: NOTIFIER_NAME + - name: NOTIFIER_NAME # e.g. jabber platform: xmpp sender: YOUR_JID password: YOUR_JABBER_ACCOUNT_PASSWORD @@ -34,7 +34,7 @@ name: description: "Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`." required: false type: string - default: Random Sensor + default: notify sender: description: "The Jabber ID (JID) that will act as origin of the messages. Add your JID including the domain, e.g. your_name@jabber.org." required: true @@ -61,7 +61,7 @@ verify: type: boolean default: true room: - description: Room's name (e.g., example@conference.jabber.org). If set, send a message to chatroom instead of the recipient. + description: "Room's name (e.g., example@conference.jabber.org). If set, send a message to chatroom instead of the recipient." required: false type: string {% endconfiguration %} @@ -74,4 +74,120 @@ room: All Jabber IDs (JID) must include the domain. Make sure that the password matches the account provided as sender. -To use notifications, please see the [getting started with automation page](/getting-started/automation/). +You can send text messages and images as well as other files through Jabber. + +### {% linkable_title Jabber Text Message %} + +Here are some examples on how to set up a script, that can be run from an automation. + +Number 1 shows a classical, text-only message. The Title is optional, although if omitted, +`Home-Assistant` will be set. To keep it empty set it to `""`. + +```yaml +# Example script.yaml entry +1_send_jabber_message: + alias: "Text only Jabber message" + sequence: + - service: notify.jabber # from notify.NOTIFIER_NAME + data: + title: "Optional Title" + message: "My funny or witty message" +``` + +### {% linkable_title Jabber Image Message %} + +You can send images or files from locally stored files or remote web locations via Jabber's HTTP Upload feature. +To send files and images, your jabber server must support [XEP_0363](https://xmpp.org/extensions/xep-0363.html). + +

+Be aware that images are uploaded onto the Jabber server of your provider. They reside there un-encrypted and could be accessed by the server admins. Usually images are deleted after a few days. +
+Home-Assistant supports TLS encryption to ensure transport encryption. TLS is enforced by default. You can disable it with the [`tls`](#tls) flag -- which is not recommended. +

+ +Number 2 sends only an image, retrieved from the URL. The TLS connection to get the image is also not verified (use with caution). + +```yaml +# Example script.yaml entry +2_send_jabber_message_with_image_url: + alias: "Send Image via Jabber from website" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url: "https://www.graz.at:8443/webcam_neu/getimg.php" + verify: false +``` + +Number 3 sends an image from a local path. + +```yaml +# Example script.yaml entry +3_send_jabber_message_with_local_image_path: + alias: "Send Image via Jabber from local file" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + path: "/home/homeassistant/super_view.jpg" +``` + +### {% linkable_title Jabber File Message %} + + +Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. Optionally you can add a timeout for the HTTP upload in seconds. + +```yaml +# Example script.yaml entry +4_send_jabber_message_with_file: + alias: "Send text file via Jabber" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url: "https://raw.githubusercontent.com/arsaboo/homeassistant-config/master/HASS%20Cheatsheet.md" + path: "Hass_Cheatsheet.txt" + timeout: 10 +``` + +### {% linkable_title Templating %} + +Number 5 sends an image retrieved from a URL, and an additional text message with `title` and `message`. + +```yaml +# Example script.yaml entry +5_send_jabber_message_with_image_and_text: + alias: "Send Image and Text via Jabber" + sequence: + - service: notify.jabber + data: + title: "The Time is now" + message: "{% raw %} {{ {% endraw %}now(){% raw %} }} {% endraw %}, templating works as well..." + data: + url: "https://github.com/home-assistant/home-assistant.io/raw/next/source/images/favicon-192x192.png" +``` + +Number 6 sends an image from a templated URL. + +```yaml +# Example script.yaml entry +6_send_jabber_message_with_image_from_url_template: + alias: "Send Image from template URL via Jabber" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url_template: "https://www.foto-webcam.eu/webcam/dornbirn/{% raw %}{{ now().year }}/{{ '%02d' % now().month }}/{{ '%02d' % now().day }}/{{ '%02d' % now().hour }}{{ (now().minute + 58) % 60 // 10}}{% endraw %}0_hd.jpg" +``` + +The possible source of a file is prioritized and only one will be picked up. `url_template` has the hightest priority; next is `url` then `path_template` and finally if none of them are defined `path` would be used. `path` will be used to eliminate file extension guessing for unknown URL downloads. Only the file extension will be left, as Home Assistant changes the filename to a random string for added privacy. + +To find out more about notifications, please see the [getting started with automation page](/getting-started/automation/).