ntfy service

• Official website
• Full documentation
• Source code
• Support

ntfy: Effortless Self-hosted Private Push Notifications¶

Source: the ntfy repository on Github

Welcome to ntfy (pronounced “notify”), your straightforward HTTP-based pub-sub notification service that is compatible with the UnifiedPush provider specification.

ntfy lets you send push notifications to your phone or desktop via scripts from any computer, using simple HTTP PUT or POST requests. It makes it possible for you to effortlessly send/receive notifications, without relying on servers owned and controlled by third parties. ntfy does not give them a chance to snoop into push notifications.

Using the UnifiedPush standard, ntfy also enables self-hosted push notifications from Matrix (and other) servers to UnifiedPush-compatible Matrix compatible client apps running on Android and other devices.

ntfy is a versatile software. With it you can send push notifications from CLI or browsers, send them with attachment files, forward push notifications to an e-mail address, and so on.

Also, ntfy is free software. There is no need for sign-ups, fees, or intricate configuration. You can run your own instance by yourself, customize it, and use it as you like, without limitation!

⚠️ Notes:

• Because iOS heavily restricts background processing, it is impossible to implement instant push notifications without a central server.
• Though the ntfy app is available for iOS (App Store; the app’s source code can be retrieved from here), any Matrix clients for iOS currently do not support ntfy due to technical limitations of the iOS platform. If you’re developing your own Matrix client app for iOS, you may need to use the Sygnal push gateway service to deliver push notifications to it.

Improve push notification’s privacy with ntfy¶

By default, push notifications received on Matrix apps on Android/iOS act merely as “wake-up calls” for the application, which contain only event IDs, and do not transmit actual message payload such as text message data.

While your messages remain private even without ntfy, it makes it possible to improve privacy and sovereignty of your Matrix installation, offering greater control over your data, by avoiding routing these “application wake-up calls” through Google or Apple servers and having them pass through the self-hosted ntfy instance on your Matrix server.

Based on UnifiedPush, ntfy ensures that push notifications to your Matrix clients will not rely on servers owned and controlled by third parties.

How ntfy works with UnifiedPush¶

⚠️ UnifiedPush does not work on iOS.

ntfy implements UnifiedPush, the standard which makes it possible to send and receive push notifications without using Google’s Firebase Cloud Messaging (FCM) service.

Working as a Push Server, a ntfy server can forward messages via the ntfy Android app as a Distributor to a UnifiedPush-compatible Matrix client such as Element Android and FluffyChat Android (see here for the definition of the Push Server and the Distributor).

The ntfy Android app is compatible with not only these Matrix clients but also other applications such as Tusky and DAVx⁵. Your ntfy server can be used for these applications too, improving your privacy as a whole.

Once configured, the applications listen to the Distributor, and push notitications are “distributed” from it. This means that the UnifiedPush-compatible applications cannot receive push notifications from the Push Server without the Distributor.

You need to install the ntfy Android app on your device in order to receive push notifications for a UnifiedPush-compatible Matrix client from the ntfy server. As the app functions as the Distributor too, you do not have to install something else on your device.

💡 Notes:

• Refer this official documentation of UnifiedPush for a simple explanation about relationship among UnifiedPush-compatible application, Distributor, Push Server, and the application’s server.
• Unlike push notifications using Google’s FCM or Apple’s APNs, each end-user can choose the Push Server which one prefer. This means that deploying a ntfy server cannot enforce a UnifiedPush-compatible application (and its users) to use the exact server.

Usage¶

To receive push notifications from the ntfy server, you need to install the ntfy Android/iOS app and then subscribe to a topic where messages will be published. You can also send/receive notifications on the ntfy’s web app at https://ntfy.your-server.com.

Install the ntfy Android/iOS app¶

To set up the Android app, you can follow the steps below:

1. Install the ntfy Android app from F-droid or Google Play.
2. In its Settings -> General: Default server, enter the ntfy server URL, such as https://ntfy.your-server.com.
3. In its Settings -> Advanced: Connection protocol, choose WebSockets.

If you are setting up the iOS app, download the app here and follow the same steps.

Subscribe to a topic¶

This step can be skipped if you use the app solely as a Distributor for the UnifiedPush-compatible Matrix clients.

After installing the app, you can create or subscribe to a topic where messages will be published. Because anyone can subscribe a topic (unless authentication is enabled), choose ones which cannot be guessed easily.

After subscribing to a topic (e.g. SR34vLnN), you can make sure that your installation is properly configured by sending a test message to it with a POST request as below:

curl -d "Test notification 🔔" https://ntfy.your-server.com/SR34vLnN

If everything works as expected, it will create a notification on your device.

Set up a UnifiedPush-compatible Matrix client¶

Having configured the ntfy Android app, you can configure a UnifiedPush-compatible Matrix client on the same device.

Steps needed for specific Matrix clients:

• FluffyChat-Android: this should auto-detect and use the app. No manual settings required.

• SchildiChat-Android:

  1. enable Settings -> Notifications -> UnifiedPush: Force custom push gateway.
  2. choose Settings -> Notifications -> UnifiedPush: Re-register push distributor. (For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in the ntfy Android app, force-close SchildiChat, re-open it.)
  3. verify Settings -> Notifications -> UnifiedPush: Notification targets as described below in the “Troubleshooting” section.

• Element-Android v1.4.26+:

  1. choose Settings -> Notifications -> Notification method -> ntfy
  2. verify Settings -> Troubleshoot -> Troubleshoot notification settings

If the Matrix client asks, “Choose a distributor: FCM Fallback or ntfy”, then choose “ntfy”.

Web App¶

The ntfy server can also be accessed via its web app where you can subscribe to and push to topics from the browser. Note that since the web app only runs in the browser locally after downloading assets for it, there is not additional security risk of running it (refer here).

Progressive Web App (PWA)¶

ntfy is built as progressive web app (PWA), which can be installed both on desktop and mobile devices. See here for more information.