Apprise integration

Apprise push notifications

PushPiper works with Apprise through its built-in Custom Form notification (forms://), free for 10,000 messages a month. One URL covers the Apprise CLI, the Python library and apps that embed Apprise.

Before you start

Grab two keys from PushPiper. Sign in at pushpiper.com/app (free, no credit card), create an app for its API token (APP_TOKEN), and copy your user key (USER_KEY) from the dashboard.

Your PushPiper URL

Apprise URL

forms://api.pushpiper.com/1/messages.json?:token=APP_TOKEN&:user=USER_KEY&:version&:type

forms:// posts a form-encoded body over HTTPS, the format PushPiper expects.
:token and :user add your keys as fields. Apprise fills in title and message itself.
:version and :type, left empty, drop two fields Apprise adds by default that PushPiper doesn't use.

Other API fields work the same way: append &:priority=1, &:sound=siren or &:url=.... Percent-encode values that contain &, :, /, + or spaces. Apprise doesn't turn + into a space, so write spaces as %20.

Send from the CLI or Python

apprise -t "Backup" -b "Nightly backup finished" \
  "forms://api.pushpiper.com/1/messages.json?:token=APP_TOKEN&:user=USER_KEY&:version&:type"

import apprise

apobj = apprise.Apprise()
apobj.add("forms://api.pushpiper.com/1/messages.json?:token=APP_TOKEN&:user=USER_KEY&:version&:type")
apobj.notify(title="Backup", body="Nightly backup finished")

apprise -t "Front door" -b "Someone rang the bell" --attach=snapshot.jpg \
  "forms://api.pushpiper.com/1/messages.json?:token=APP_TOKEN&:user=USER_KEY&:version&:type&attach-as=attachment"

attach-as=attachment, without a colon, sends the --attach file as a multipart field named attachment, which is what the API reads. One image per message, up to 5 MB.

We ran all three against a test server with Apprise 2.0.1 and checked every field that arrived. The CLI exits with code 1 when a message is rejected, so scripts notice. Add -v to see the HTTP status.

Handy URL options

In the URL	What it does
`&:priority=1`	High priority, bypasses quiet hours
`&:priority=2&:retry=60&:expire=3600`	Emergency: repeats every 60 seconds until acknowledged, for up to an hour
`&:sound=siren`	One of the 23 built-in sounds
`&:url=https%3A%2F%2Fexample.com&:url_title=Open`	A link under the message
`:user=KEY1,KEY2`	Several recipients, up to 50 keys, instead of one `USER_KEY`
`&attach-as=attachment`	Sends `--attach` files the way the API expects

Details on every field are in the API reference.

Limits and caveats

`pover://` is Pushover-only. Its address is fixed to api.pushover.net.
Pass a title. Without -t, Apprise still sends a title field, just empty.
Stick with `forms://` for files. jsons:// also works for text if you drop &:attachments too, but it can't send attachments in a format PushPiper reads.
Apps that embed Apprise take the same URL. Uptime Kuma ships Apprise in its Docker image, for example.

Sources

Questions and answers

Can I use Apprise's Pushover URL (pover://) with PushPiper?

No. The Pushover plugin always posts to api.pushover.net. Use the forms:// URL on this page, which sends the same Pushover-style fields to PushPiper.

Why add :version and :type to the URL?

Apprise's form plugin adds version and type fields to every message. Listing them with no value removes them, so PushPiper only gets fields it knows.

How do I notify a whole team?

Put up to 50 user keys, separated by commas, in :user, or use a group key.

Can I send images?

Yes. Use forms:// with attach-as=attachment and the --attach option. One image per message, up to 5 MB.