Subscribe from your phone¶
You can use the ntfy Android App to receive notifications directly on your phone. Just like the server, this app is also open source. Since I don't have an iPhone or a Mac, I didn't make an iOS app yet. I'd be awesome if someone else could help out.
A picture is worth a thousand words. Here are a few screenshots showing what the app looks like. It's all pretty straight forward. You can add topics and as soon as you add them, you can publish messages to them.
If those screenshots are still not enough, here's a video:
When you publish messages to a topic, you can define a priority. This priority defines how urgently Android will notify you about the notification, and whether they make a sound and/or vibrate.
By default, messages with default priority or higher (>= 3) will vibrate and make a sound. Messages with high or urgent priority (>= 4) will also show as pop-over, like so:
You can change these settings in Android by long-pressing on the app, and tapping "Notifications". You can then configure the settings (and custom sounds or vibration) for each of the priorities:
Instant delivery allows you to receive messages on your phone instantly, even when your phone is in doze mode, i.e. when the screen turns off, and you leave it on the desk for a while. This is achieved with a foreground service, which you'll see as a permanent notification that looks like this:
Android does not allow you to dismiss this notification, unless you turn off the notification channel in the settings. To do so, long-press on the foreground notification (screenshot above) and navigate to the settings. Then toggle the "Subscription Service" off:
Limitations without instant delivery: Without instant delivery, messages may arrive with a significant delay (sometimes many minutes, or even hours later). If you've ever picked up your phone and suddenly had 10 messages that were sent long before you know what I'm talking about.
The reason for this is Firebase Cloud Messaging (FCM). FCM is the only Google approved way to send push messages to Android devices, and it's what pretty much all apps use to deliver push notifications. Firebase is overall pretty bad at delivering messages in time, but on Android, most apps are stuck with it.
The ntfy Android app uses Firebase only for the main host
ntfy.sh, and only in the Google Play flavor of the app. It won't use Firebase for any self-hosted servers, and not at all in the the F-Droid flavor.
UnifiedPush is a standard for receiving push notifications without using the Google-owned Firebase Cloud Messaging (FCM) service. It puts push notifications in the control of the user. ntfy can act as a UnifiedPush distributor, forwarding messages to apps that support it.
To use ntfy as a distributor, simply select it in one of the supported apps. That's it. It's a one-step installation 😀. If desired, you can select your own selfhosted ntfy server to handle messages. Here's an example with FluffyChat:
React to incoming messages¶
To react on incoming notifications, you have to register to intents with the
io.heckel.ntfy.MESSAGE_RECEIVED action (see code for details). Here's an example using MacroDroid and Tasker, but any app that can catch broadcasts is supported:
For MacroDroid, be sure to type in the package name
io.heckel.ntfy, otherwise intents may be silently swallowed. If you're using topics to drive automation, you'll likely want to mute the topic in the ntfy app. This will prevent notification popups:
Here's a list of extras you can access. Most likely, you'll want to filter for
topic and react on
| ||string|| ||Randomly chosen message identifier (likely not very useful for task automation)|
| ||string|| ||Root URL of the ntfy server this message came from|
| ||string|| ||Topic name; you'll likely want to filter for a specific topic|
| ||bool|| ||Indicates whether the subscription was muted in the app|
| ||string ( || ||Same as |
| ||int|| ||Message date time, as Unix time stamp|
| ||string|| ||Message title; may be empty if not set|
| ||string|| ||Message body; this is likely what you're interested in|
| ||string|| ||Comma-separated list of tags|
| ||string|| ||Map of tags to make it easier to map first, second, ... tag|
| ||int (between 1-5)|| ||Message priority with 1=min, 3=default and 5=max|
Send messages using intents¶
To send messages from other apps (such as MacroDroid and Tasker), you can broadcast an intent with the
io.heckel.ntfy.SEND_MESSAGE action. The ntfy Android app will forward the intent as a HTTP POST request to publish a message. This is primarily useful for apps that do not support HTTP POST/PUT (like MacroDroid). In Tasker, you can simply use the "HTTP Request" action, which is a little easier and also works if ntfy is not installed.
Here's what that looks like:
The following intent extras are supported when for the intent with the
| ||-||string|| ||Root URL of the ntfy server this message came from, defaults to |
| ||✔||string|| ||Topic name; you must set this|
| ||-||string|| ||Message title; may be empty if not set|
| ||✔||string|| ||Message body; you must set this|
| ||-||string|| ||Comma-separated list of tags|
| ||-||string or int (between 1-5)|| ||Message priority with 1=min, 3=default and 5=max|
I almost feel devious for putting the Download on the App Store button on this page. Currently, there is no iOS app for ntfy, but it's in the works. You can track the status on GitHub.