Sending Notifications from a Shell Script

Having verified that your ntfy setup is functional, it's time to send notifications from your services or shell scripts. Consider an example of a backup script. Upon completion of the backup process, you might wish to send a notification detailing its status. To do this, first create a user for this script and give it write permissions to a specific topic, backup:

/ # ntfy user add backup
user backup added with role user
/ # ntfy access backup backup write-only
granted write-only access to topic backup
user backup (role: user, tier: none)
- write-only access to topic backup

Because publishing a message just involves sending an HTTP POST or PUT request to the web server, this is as easy as executing a curl [4] command:

$ curl -u backup:password \
  -d "Backup successful" \
  ntfy.example.com/backup

Subscribe to this topic in your mobile app to receive this notification.

You can use this simple approach in all your shell scripts.

Embellishing Your Notification Messages

Ntfy supports numerous extra features to embellish your messages or modify their behavior. You can include many of these by adding an HTTP header to your request. For instance, you can add a title, a message priority, and tags that are shown as icons. An example is shown in Listing 4, with the resulting notification on Android shown in Figure 4.

01 $ curl -u backup:password \
02   -H "Title: Backup failure" \
03   -H "Priority: urgent" \
04   -H "Tags: warning,skull" \
05   -d "Backup unsuccessful" \
06   ntfy.debian.home/backup

Figure 4: You can add a title, priority, and icons to a ntfy message.

Note that because of the urgent priority, the Android app responds differently than in the previous example: Apart from playing the default notification sound, it also keeps vibrating for a time. With the default priority, only a short vibration and sound occur.

You can also send pictures, although you can't combine this with a text message. The procedure is detailed in Listing 5. Specify the local file path after curl's -T option to upload the file using an HTTP PUT request, and add the same file name in the Filename header so the ntfy app knows what file name to offer you.

01 $ curl -u admin:password -T egg.jpg \
02   -H "Filename: egg.jpg" \
03   -H "Title: Egg ready" \
04   -H "Tags: egg" ntfy.debian.home/egg

If you want to combine a picture with text, format your messages using Markdown [5] and include a link to an online picture. However, this feature is only supported in ntfy's web interface. The Android or iOS apps just display the Markdown source of your message.

To send a Markdown message, set the Markdown header to yes or the Content-Type header to text/markdown, after which the ntfy web app interprets the messages as Markdown rather than plain text. This allows you to make text bold or italic, add links and images, and include lists. Note that only basic Markdown features are supported.

Notifications with Actions

Notifications appear within your app in a list per topic, but if you tap on a notification, by default this just copies the message to your clipboard. However, you can also specify a URL that opens when you tap on the message. For instance, in a notification from your backup server, you can include a link to the backup server's admin interface, as shown in Listing 6. Unfortunately, the Android app doesn't indicate in any way that there's a click action defined, but the link automatically opens when tapped.

01 $ curl -u backup:password \
02   -H "Click: https://pow.home:8007" \
03   -d "Backup successful" \
04   ntfy.example.com/backup

Beyond this, ntfy offers action buttons for notifications. Users can tap on up to three buttons shown beneath the message, leading to the opening of a website or app, the sending of an Android broadcast intent [6] that other apps can react to, or the sending of an HTTP POST/GET/PUT request.