Tag Archives: Configuration

Apprise, Linux HOWTO

Setup Apprise Notifications on Home Assistant

1 Comment

Introduction

Apprise allows you to notify just about all of the most popular notification services out there. In fact, there were more then 65 supported services at the time of writing this blog. By integrating it into your Home Assistant environment:

  1. You can securely define all of your notification service end points in one easy to manage location. You can even store these endpoints in configuration elsewhere on your network by leveraging the API allowing you to centralize your configuration and/or decouple it.
  2. You don’t have to try to find the specialized Home Assistant integration for a service you use because most likely Apprise already supports it!
  3. All of the notifications are all sent asynchronously; hence everything gets notified at the same time and not one after another.
  4. You can leverage tagging to easily filter the flow of what messages go where (all explained in this blog).
Home Assistant Apprise Overview
Home Assistant Apprise Overview

Apprise In A Nutshell

Let’s start with the basics… Apprise is built around ingesting specifically formatted URLs which provides it everything it needs in order to send a notification. The URLs are structured as {service}://{credentials}. For example, below are a few of the the most popular services based on traffic to it’s wiki page:

  • TelegramFor a Telegram Notification the Apprise URL looks like:
       tgram://{bot_token}/{chat_id}
       You can read more about the structure here
  • DiscordFor a Discord Notification the Apprise URL looks like:
       discord://{WebhookID}/{WebhookToken}
       You can read more about the structure here
  • EMailFor an Email the Apprise URL looks like:
       mailtos://{user}:{password}@{host}
       You can read more about the structure here

Feel free to have a look at all of the supported Apprise notification services and their accompanying URL documentation here. You can optionally also have a look at this blog entry too if you wish to to test your URL outside of Home Assistant.

Home Assistant Integration

URL Based Setup

The following simple Home Assistant package will get you started in your configuration.yaml file:

# inside your configuration.yaml file:
notify:
  name: apprise
  platform: apprise
  # A Hotmail Example:
  url: "mailto://user:pass@hotmail.com"

Next you can create a simple automation that fires off your notification:

# An example automation:
automation:
- alias: "[Interactive] - Sunset Notice"
  trigger:
    platform: sun
    event: sunset

  action:
    service: notify.apprise
    data:
      title: "Good evening"
      message: "This sun is setting."

There are no limits to the number of Apprise URLs you define. The more you identify, the more that get automatically notified when you reference the notify.apprise service. You can identify more then one notification endpoint by simply updating your entry in your configuration.yaml file to look like so:

# inside your configuration.yaml file:
notify:
  name: apprise
  platform: apprise
  url:
    # A Hotmail Example:
    - "mailto://user:pass@hotmail.com"
    # A Slack server:
    - "slack://MY/TOKEN/INFORMATION"
    # A KODI Server
    - "kodi://my.kodi.server.local"

Apprise File Based Configuration Setup

If you leverage the Apprise configuration as an access point of your Home Assistant setup, you have the power to do a lot more customization with your notifications and how they are triggered. Let’s start with what your entry would look like in your configuration.yaml file:

# inside your configuration.yaml file:
notify:
  name: apprise
  platform: apprise
  # use the 'config' keyword
  # configuration file:
  config: /config/apprise.yaml

Now here is what your Apprise configuration file might look like:

# /config/apprise.yaml
# Our Apprise Configuration File leveraging Tagging
#
urls:
  # Set up a email notification
  - "mailtos://user:mysecretpassword@gmail.com":
    - tag: me, family
      to: myuser@gmail.com
    - tag: family
      to: myspouse@gmail.com, mykid@gmail.com

  # Set up a PushBullet notification
  - "pbul://o.jh33GTY7fpMCbl5gsp8Wk6IJOu43AqCC":
    - tag: me, pushbullet
  - "pbul://o.yy44GTY7fpMCbl5gsp6Aw6IJOu43AqDD":
    - tag: spouse, pushbullet

  # Setup our KODI instances and assign them both to the
  # tv tag
  - "kodi://kitchen.pi.lead2gold.local":
    - tag: tv

  - "kodi://livingroom.pi.lead2gold.local":
    - tag: tv

  # Our DevOps team at work
  - "slack://SPECIAL/TOKEN":
    - tag: devops

The above configuration file leverages tagging by assigning 1 or more tags with all of the identified notification end points. This plays a big roll into how you define your automations now.

Now automation might now look like this:

# An example automation to notify everything identified:
automation:
- alias: "[Interactive] - Sunset Notice"
  trigger:
    platform: sun
    event: sunset

  action:
    service: notify.apprise
    data:
      # 'all' is a special keyword that will cause
      # everything to get notified regardless of the
      # tag already associated with it. 
      target: all
      title: "Good evening"
      message: "This sun is setting."

But by leveraging tagging, we can customize our notifications to just address ‘some’ of the endpoints we identified:

# An example automation to notify everything identified:
automation:
- alias: "[Interactive] - Download Completed"
  trigger:
    platform: event
    event_type: nzbget_download_complete

  action:
    service: notify.apprise
    data:
      # Just notify the services that have the tv tag
      # associated with them. This will not notify
      # anything that does not have the identified tag
      # associated with it:
      target: tv
      title: "Download completed!"
      message: "{{trigger.event.data.name}}"

Where things get really cool, is Apprise is smart enough to work our OR‘s and AND‘s.

For cases where you only want to notify entries that have tagA AND tagB associated with them, you would do the following:

#
# Leverage the 'AND' keyword
# ...
action:
  service: notify.apprise
  data:
    # Just notify the services that have the me AND family
    # tag associated with them.
    # This will not notify anything that does not otherwise
    # meet this criteria:
    target: me, family
    title: "Explicitly matching Tags using AND"
    message: "I will only notify myuser@gmail.com defined in the example above."

The more tags you identify that are separated, the more AND’ing (and more restrictive) the check becomes.

For cases where you only want to notify entries that have tagA OR tagB associated with them, you would do the following:

#
# Leverage the 'OR' keyword
# ...
action:
  service: notify.apprise
  data:
    # Just notify the services that have the tv, pushbullet,
    # or me tag associated with them.
    target:
      - me
      - pushbullet
      - tv
    title: "Explicitly matching Tags using OR"
    message: >-
        This triggers on everything except the `devops` Slack post and the
        emails to myspouse@gmail.com and mykid@gmail.com that were defined
        above under the 'family' tag which wasn't identified in the targets

You may have guessed it now, but if you want to combine OR and AND together, you just identify them as such:

#
# Leverage the 'OR' and the 'AND' keyword
# ...
action:
  service: notify.apprise
  data:
    # Just notify the services that have the me AND family tag associated with
    # it.  Also include any services that have the devops tag as well.
    target:
      - me, family
      - devops
    title: "Email myself only and notify Devops on Slack"
    message: >-
        Testing out the AND and OR together

Now you might be asking: Why would I have my DevOps team be part of my Home Assistant configuration? Well the answer to this question makes more sense in the next section.

Apprise Web Based Configuration Setup

Apprise follows a universal configuration and has already been integrated in many other platforms. If you’re using Apprise elsewhere on your network (or with a team), you may have chosen to host a central configuration. This way you can define all of your Apprise URLs in one location (and not have them spread out across your other servers). If you set up tagging appropriately, you’ll be able to notify only the specific endpoints required; nothing more, nothing less. For those taking advantage of the API (a cloud based centralized configuration end point), you just need to point your Home Assistant Configuration to it as http://apprise.server.local:8000/get/{KEY} where {KEY} is what where you set your configuration up as. So your configuration.yaml file might look like this:

# inside your configuration.yaml file:
notify:
  name: apprise
  platform: apprise
  # Retrieve our Apprise configuration from a remote location.
  # with respect to the below, we're using the default `apprise`
  # key/token:
  config: http://apprise.server.local:8000/get/apprise

Credit

This blog took me a very (,very) long time to put together and test! If you like what you see and wish to copy and paste this HOWTO, please reference back to this blog post at the very least. It’s really all I ask. Alternatively, I certainly won’t turn down a coffee if you wish to buy me one! 🙂

Sources