# ntfy## ntfy: self-hosted, private push notifications

![ntfy](https://etke.cc/img/extra-services/ntfy/ntfy.webp)

*Source: the [ntfy repository on Github](https://github.com/binwiederhier/ntfy/blob/main/.github/images/screenshot-web-detail.png)*

**ntfy** (pronounced “notify”) is a simple HTTP-based pub-sub notification service, compatible with the [UnifiedPush provider specification](https://unifiedpush.org/).

ntfy lets you send push notifications to your phone or desktop via scripts from any computer, using simple HTTP PUT or POST requests. It lets you send and 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](https://unifiedpush.org) 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](https://apps.apple.com/us/app/ntfy/id1625396347); the app’s source code can be retrieved from [here](https://github.com/binwiederhier/ntfy-ios)), **any Matrix clients for iOS currently do not support ntfy** due to [technical limitations of the iOS platform](https://github.com/binwiederhier/ntfy-ios/blob/main/docs/TECHNICAL_LIMITATIONS.md). If you’re developing your own Matrix client app for iOS, you may need to use the [Sygnal](https://etke.cc/help/extras/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.**](https://unifiedpush.org/users/faq/#will-unifiedpush-ever-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](https://docs.ntfy.sh/subscribe/phone/) as a **Distributor** to a UnifiedPush-compatible Matrix client such as Element Android and FluffyChat Android (see [here](https://unifiedpush.org/users/distributors/#definitions) 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](https://tusky.app/) and [DAVx⁵](https://www.davx5.com/). 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 notifications 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](https://docs.ntfy.sh/subscribe/phone/) 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](https://unifiedpush.org/users/troubleshooting/#understand-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](https://docs.ntfy.sh/subscribe/phone/)** 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](https://docs.ntfy.sh/subscribe/phone/) 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](https://apps.apple.com/us/app/ntfy/id1625396347) 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:

```sh
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”.

![ntfy Main Screen](https://etke.cc/img/ntfy/ntfy-main.webp) ![ntfy Settings Screen](https://etke.cc/img/ntfy/ntfy-settings.webp) ![Matrix Client App Notification Settings](https://etke.cc/img/ntfy/matrix-notification-settings.webp)

#### 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](https://docs.ntfy.sh/faq/#can-i-disable-the-web-app-can-i-protect-it-with-a-login-screen)).

##### Progressive Web App (PWA)

ntfy is built as [progressive web app (PWA)](https://docs.ntfy.sh/subscribe/pwa/), which can be installed **both on desktop and mobile devices**. See [here](https://docs.ntfy.sh/subscribe/web/#background-notifications) for more information.


---
* [llms.txt](https://etke.cc/llms.txt): full site index in markdown