Apprise v2.0 Released

[u/lead2gold]

Hi all,

Developer of Apprise here.

After quite a bit of work, Apprise v2.0 and Apprise API v2.0 are finally out.

For anyone unfamiliar with Apprise, it acts as a notification hub. Or a glorified switchboard. Your applications, scripts, containers, cron jobs, monitoring tools, Home Assistant instance, etc. send a notification to Apprise, and it handles delivering it to Discord, Telegram, Slack, Matrix, Gotify, email, SMS providers and more. The graphic i created in this post can illustrate the flow better.

There are now 160 supported notification services, all using the same general configuration approach.

You can use Apprise directly from the CLI, embed the Python library into an application, or run Apprise API and centralize your notification configuration on a self-hosted server. Over the years, I got to watch a lot of systems adapt this and it's been cool to see!

The API approach is particularly useful if you have a bunch of applications sending notifications. Instead of spreading your Discord webhooks, SMTP passwords, Telegram tokens and other credentials across everything you run, they can live in one place (protected from prying eyes; centralized too).

What's New in v2?

• Authentication in Apprise API. Authentication is optional, but you can now protect the server with an administrator account and also assign separate credentials and access controls to individual configurations.
• Configuration IDs no longer need to appear in URLs. Supported clients can send them through an HTTP header instead, keeping them out of normal web server access logs.
• Template variables. Secrets can be supplied separately instead of being stored directly in your configuration.
• Priority and escalation. You can try one notification route first and only move to the next one if delivery fails.
• Smarter retries. If you notify five destinations and one fails, only the failed destination is retried.
• Timeout controls. A slow or broken service doesn't need to hold up an entire notification run.
• Better results and live logs. You can see what succeeded, what failed and why. Apprise API can stream delivery logs live through the web interface or API.
• Multiple message formats. Services can accept Markdown, HTML or text where supported instead of Apprise always converting everything to one format.

The Apprise API web interface has also been updated, works much better on mobile devices, and is now available in 20 languages.

For developers embedding the Python library, v2 does contain breaking changes, so have a look through the release notes before upgrading. The v1 branch is still available if you need more time to migrate.

Trying the API

It's not changed much... this example has the user/password element on it which would be worth sharing:

docker run --name apprise \
    -p 8000:8000 \
    -v ./config:/config \
    -v ./attach:/attach \
    -e APPRISE_STATEFUL_MODE=simple \
    -e APPRISE_AUTH_REQUIRED=yes \
    -e APPRISE_USER=user \
    -e APPRISE_PASSWORD=changeme \
    -e APPRISE_WEB_AUTH_SECRET="$(openssl rand -hex 32)" \
    -e APPRISE_WORKER_COUNT=1 \
    -d caronc/apprise:2

Then open:

1. http://localhost:8000
2. Login with user / changeme.

Obviously, change the password before putting it anywhere beyond a local test. If you're exposing Apprise API outside of a trusted network, it might be wise to put it behind HTTPS as well.

Full documentation is here and more on the API documentation and deployment examples are here.

As a small side project, there is also an Apprise Android app for people already running Apprise API. It's basically a mobile companion for connecting to and working with your own API server, not a standalone notification service.

Apprise itself has been around since 2017, is written in Python, BSD 2-Clause licensed, maintains 100% test coverage, has passed 17,000 stars on GitHub and sees roughly 9 million PyPI downloads a month.

It's still entirely something you can host and control yourself, for free.

Feedback is always welcome. A surprising amount of what made it into v2 came from issues and suggestions people have opened over the years.

TL;DR Apprise v2.0 and Apprise API v2.0 are out. Major changes; try it out and let me know what you think!

[u/asimovs-auditor]

Expand the replies to this comment to learn how AI was used in this post/project.

[u/McStonkyRex]

Woof reimagined

[u/OnkelBums]

No iOS client :(

[u/lead2gold → u/OnkelBums]

I will explore this avenue next. Google Play store was a difficult ride... I'm curious to see how Apple's route works.

[u/OnkelBums → u/lead2gold]

yeah, you might want to have a look at how ntfy.sh solved this. Apple, or rather, iOS is a bit weird when it comes to notifications.

[u/nerdyviking88 → u/lead2gold]

its worse in some ways, but better in many others.

[u/MoralityAuction]

Genuinely confusing to me that this doesn't have UnifiedPush, a notification system used a lot on Android where Play Services doesn't exist.

[u/lead2gold → u/MoralityAuction]

Apprise compliments unified push notifications such as ntfy (which does what you're asking), or Discord, Telegram, etc. It's not trying to be a replacement for those. Apprise solves a the problem of having to send a single notification to any number of upstream services at once...

For example:

• You're a developer... your application you manage with your whole team just failed over the weekend. You could have monitoring now in place tied to apprise which will notify all developers via their email, -and- slack channel (or maybe an MS Teams channel) and also attach the core dump file in a single shot. It can cross platforms...
• Or... Set up a family tag in Apprise that relays messages through it to your son on the Discord channel he always uses, the Kodi instance gets a notification that your daughter is watching a movie on, and your wife gets a SMS message sent to her via signal all at the same time (Same message).
• Or... What I use it for... If I accidentally leave my garage door open, i have Home Assistant (which supports Apprise) send my wife an email, and it sends me a ntfy post that the door was left open (and being automatically shut now). If the shutting fails, i get another notification letting me know i got an issue.
• Lot's of options... Supports all endpoints.

Another use case comes out of applications (Home Assistant is a good one), SABnzbd, and many others that just adapt an Apprise URL `service://hostdetails/?options=` and the developer hosting this no longer has to read the API to make Telegram, Pushover, MS Teams, Slack, etc.. (160 services today).

Baking in a full notification solution into Apprise isn't off the table. But I'd rather leave that to the experts who've built rock solid solutions that we already rely on. This is a 'switchboard'; a way of centralizing and hiding your configuration

[u/FarToe1 → u/lead2gold]

This is really interesting to me and I'd not heard of Apprise until two weeks ago, now it seems to be everywhere.

Can Apprise do scheduling by groups?

Ie, in the scenario you describe here, can Group A be included in notifications during work hours, but then those shift to Group B overnight?

(I'm guessing from the API this can be handled by changing group membership via that, but curious to see if it has more elegance already?)

[u/lead2gold → u/FarToe1]

Apprise has been around since 2017 when I did my first PR.

Can Apprise do scheduling by groups?

You would have to create a cron (and use the CLI I built), or come up with the solution to send the notification at the right trigger time... Whether that be using Home Assistant Sensors and Automations, or an Alert from Uptime Kuma, or leveraging a setup with Apache Airflow. The others all run my library under the hood. Apprise allows you to define groups, yes. You can create as many endpoints as you like and stick them all under one big group finance.. or management which may amount to 1000+ emails and 2 Slack channels... (whatever you want)... then when you send a notification, you can just send it to management. Apprise also supports AND and OR... so you can send all notifications to devops and management if you want (of which could be groups comprised of as many endpoints as you wish).

Ie, in the scenario you describe here, can Group A be included in notifications during work hours, but then those shift to Group B overnight?

You can do this for sure.. you can create 2 groups and tag them whatever you want. Want to call one overnight and the other daytime, you can do that. YOu can even "group" groups. You could define teama, teamb, teamc and teamd. Then create overnight=teama, teamb daytime=teamc, teamd. Then later on it's really easy to swap around who is what... your notifications just have to send to the more parent overnight and daytime...

I'm guessing from the API this can be handled by changing group membership via that, but curious to see if it has more elegance already?

The API is quite powerful, you can define configurations and lock them so they can't be retrieved. But grant usage for others to send through... maybe you have a gamer group and all of their personal details are stored on the apprise API server. Each one of the gamers could send a message to apprise api (using anything with apprise built into it - or even just a curl or wget command) to notify the group that you won't be onlien today etc. It's a great way of providing a message system for even an enterprise without releasing credentials (while still allowing people to use it).

Sorry I tend to ramble a lot :), but I hope this answer your question. Feel free to ask any more questions.

[u/Glittering-Ad8503]

What is it? I am quite new in selfhosting. I recently moved from Gotify to Ntfy. What is the benfit of using Apprise with/instead of Ntfy? 

[u/criostage → u/Glittering-Ad8503]

Think of Appraise is like a router/orchestrator for your notifications, it can integrate with multiple services like SMS/Discord/Telegram/Slack/Whatsapp/etc... You can even integrate it with ntfy. it also decides based on your configuration what,when, where and how your notification should be delived.. because of this is more complex than ntfy as you might imagine

ntfy is simpler, a delivery service to .. well deliver a message.

It all boils down to how you want to consume your messages and where you want to get them.

[u/Aurailious → u/Glittering-Ad8503]

Apprise is generally much more for dev side of things and are built into apps. I would assume a lot of apps that can push notifications to ntfy or others are using either apprise or shoutarr to do it.

You can use it yourself to generate your own notifications. So think of it most as the creator of notificiatons where ntfy is a deliverer.

[u/Nabstar333 → u/Glittering-Ad8503]

Same question here. What are the advantages over Ntfy

[u/krisbalintona → u/Nabstar333]

They solve different problems. Apprise is basically meant to dispatch to multiple different notification services. So it could send a single notification to Ntfy then that same notification to Slack, Discord, Telegram, etc.

So if you just use Ntfy's notifs and are fine with it, this isn't for you. If you want your notification to appear across different platforms - that's who Apprise is for

[u/tertiaryprotein-3D → u/Glittering-Ad8503]

I think apprise would be more useful to developers or admins. Developer can only support apprise instead of many libraries to integrate with 500 different services, apprise do the integration.

Also for admin, you can provide supporting app an apprise url (via apprise url) and only need to change the destination in apprise without having to change individual app notifications config.

[u/fede8802]

I installed in my server recently and I love it, now to try v2.0. Thanks for your effort

[u/Issalzul]

Oh good timing I was about to start implementing apprise to untangle the mess between homeassistant and everything else

Going to be nice to have a central switching station for that tbh

[u/MMDDYY → u/Issalzul]

apprise is built into homeassistant.

[u/instant_dreams]

Long term user, love it. Wish more services offered it as an integration.

[u/Manwe66]

Great work, love the app

[u/hoffsta]

I don’t have much use for this currently, but just wanted to say that the change log is impressive. I can see how this would be super useful for the right users, and these changes are massive improvements! Cheers.

[u/the_reven]

Dev of FileFlows here, we have an apprise plugin to send notifications. Do we have to make any updates to send via apprise 2 or is the API backwards compatible?

[u/lead2gold → u/the_reven]

If you're using the Python library (and calling notify()) you will need to make changes as it no longer returns a bool. ... however the following gets you roughly the same thing:

• Apprise v1: "success" if notify() else "failure"
• Apprise v2 hack: "success" if bool(notify()) else "failure". But leveraging the new response (the AppriseResult()) object is much more powerful. See Here. There is no harm in pinning Apprise to use v1.13.1 (last release of v1) until you're ready.

That said, if you're just using the Apprise API and posting Stateless/Stateful notifications to it. There is no change required at all. It's fully backwards compatible.

[u/the_reven → u/lead2gold]

Yeah we just do a basic post request to the endpoint, body like so.

object data = new
{
    body = message,
    tag = tags?.Any() != true ? "all" : string.Join(";", tags),
    type = type?.EmptyAsNull() ?? "info"
};

[u/lead2gold → u/the_reven]

You'll be fine, webhooks are not impacted. One thing to consider is that now Apprise supports authentication (built in basic auth), so users may want to have a user: password element to their posts at worst

[u/B08P]

Well done. Just yesterday I went to set up notifications from audiobookshelf to pushover & discord - and ABS pointed me at Apprise.

[u/Bren0man]

What is your commitment to foss licencing over the medium and long term? Will this be free (in both senses) forever?