Notifications for Audio Bookshelf Using Apprise and Home Assistant

Apprising The Situation

Recently, I’ve been on a “self host all the things” kick and my latest adventure has been with Audio Bookshelf. It allows me to self-host my podcasts, audiobooks and books in one place. It has Android/IPhone apps as well as a web front-end. I use wireguard to access it when out of the house, or I can download what I need proactively onto my device. It’s pretty great. I run it in a LXC using a script from tteck.

I use Calibre and Open Audible to free my purchases for self-hosting.

App Front End

Web Front End

One of the things that were missing though, were notifications for new podcast episodes. Going through the settings, I saw that a requirement for this was an “Apprise” server.

Apprise is a self hosted notification service that can push messages to many, many different destinations. And I was thrilled to see that Home Assistant was among them. I am a novice to a lot of this, and my 13 year old son and I are just starting to learn Python together so that’s my entry point.

Note: you do not need to know Python for this, just providing some perspective.

At the end of my effort I was able to light up Apprise as a docker (using the LXC Docker/Portainer script from tteck) and then successfully send notifications from ABS to HA, then to Node-Red to push said notifications to my devices. Let’s get into that process now.

Setup

The first step is to go to the Apprise server and click on “New Configuration”

Then open a new window for the “Notification Services” page which will list the variables for all the supported destinations. for HA I am going to use the top one,
hassio://{host}/{long-lived-access-token} Paste your HA install IP into the host section as well as your long lived access token from HA. In my install I had to remove the curly braces for the “save” to tell me the URL was correct.

To get the token from HA, click on your name on and then scroll all the way down.

My config looks like:

Now you can test the integration.

In HA it should be in your Notification Area. I use the Nabu Casa service from HA for external access via reverse proxy, but still had no issue sending the notification directly to the install via local IP.

Now, let’s continue the config in Audio Bookshelf. (ABS) The web front-end has the majority of config options. Go to Settings>Notifications

The API url is http://[host:port]/notify/[name of apprise config]
The name can be anything, it will be listed on the overview screen. Save the config.

Then create notification. I use the onPodcast one since you can fire off a test notification at any time with either one. I also modified my Title template to be:
New {{podcastTitle}} Episode: {{episodeTitle}}

The apprise URL will be:
http://[host:port]/cfg/[name of apprise config]

8/29/24
NOTE: I received some feedback from a reader who was having difficulties at this step. The difference was their deployment (ABS/Apprise) was all in the same docker, whereas my ABS is in a LXC. The statement was:

In the "apprise URL" field I entered "apprise://apprise:8000/homeassistant"

Once submitted, we can fire off a test from within ABS. If successful, you’ll get a green check.

Now let’s check HA to see if it arrived.

Excellent! We’re almost done. Let’s make the notification a push to a device with Node-Red. I’m not going to get terribly in the weeds with NR here, see this post for a more detailed breakdown.

Using Node Red for Push Notifications.

So you will need the official HA mobile app for notifications, and NR installed on HA as an addon.

HA generates messages for everything that happens in the system. There is not a special node for just notification traffic so we need to look at the structure of the message to filter it out, and build out our own filter.

First, let’s use the events:all and debug node. We need to be careful to try an avoid leaving the event type blank if at all possible.

For this we’ll use the “call_service” as the event type to start as our filter.
I already bogged down my server to find the right event type, this saves you that step.

Now after running a test, we’ll see it in our debug output.

Now, in order for us to target this specific message, we will also use a “switch” node to filter further.

With msg.payload.event.service_data.message I will filter on “contains Podcasts” There are far, far, more elegant ways to do this but it works for me. Do what works for you. :)

Now that we have our notifications properly filtered, we need to send it to a device. When you install the HA app, it registers to HA as a referenceable entity. We will use a “call service node” and tie it to the output of the switch node.

The domain will be notify, and the service is the device the app is installed on. We also need to have the data section filled out.

Here is the JSON that works for this example.

{

    "message": "{{payload.event.service_data.title}}",

    "data": {

        "color": "green",

        "channel": "ABS",

        "priority": "high",

        "ttl": 0

    }

}

With the HA app, you can create a notification “channel” to have different alerts on the remote device. When you send this finished flow to HA the first time it will then create the channel on the app. It is not configured directly on HA in this method. Without NR, you would create the channel in configuration.yaml and this whole process would be very different.

On the app, to see your channels, go to Settings>Companion App>Notification Channels.

Now, go back to ABS and fire off a new test, and consider yourself notified!

Until next time!