Sending messages

Two ways to send

The app's webhook URL

The token is part of the URL, so it's all a service or script needs. Post a form, JSON, or plain fields:

curl https://api.bzzd.io/v1/hooks/APP_TOKEN \
  -d title="Backup" \
  -d message="Backup finished on nas-01"

The API, with the token in a header

For your own code, where the token can stay out of URLs and logs:

curl https://api.bzzd.io/v1/messages \
  -H "Authorization: Bearer APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy", "message": "shop/web is live", "link": "https://shop.example.com"}'

Both take the same fields. Webhook URLs also understand the formats of the services in the integrations.

Fields

As JSON, a form, or query parameters. Only message is required.

message

The text, up to 1,024 characters. Longer text is shortened, not refused.

title

Shown in bold above the text, up to 250 characters. Without it, the app's name is the title.

link

A URL to open when the notification is tapped, up to 512 characters.

link_title

What the link is called in the inbox, up to 100 characters.

priority

One of silent, quiet, normal (the default), high or urgent. See Priorities.

devices

Device names, as a list or separated by commas, to send to only those. Without it, every device gets it.

image

A picture to show with the message. See Images.

expires_in

Seconds the push service keeps trying a device that's offline; after that, the notification is dropped (it stays in the inbox).

to

For a shared app: the user key of one member to send to. Without it, the owner and every member get it.

repeat_every, repeat_for

Urgent messages only. See Urgent messages.

Things that look like passwords or tokens in the text, title or link (in URLs, Bearer headers, or keys from GitHub, GitLab, Slack, AWS, Stripe and others) are replaced with ••• before the message is saved.

Priorities

silent

No sound or vibration. Phones may hold it until they wake up. For logs you only want in the inbox.

quiet

No sound or vibration, and may wait while the phone is idle.

normal

Alerts right away, with the device's notification sound.

high

Alerts right away, and is marked High in the inbox, where you can filter for it. Services' failures arrive as high.

urgent

Stays on screen until dismissed, and repeats until someone acknowledges it.

Urgent messages

An urgent message alerts again every repeat_every seconds (at least 30) until someone taps Acknowledge, deletes it, or repeat_for seconds have passed (at most 10,800, three hours). Both are required:

curl https://api.bzzd.io/v1/hooks/APP_TOKEN \
  -d message="Database is down" \
  -d priority=urgent -d repeat_every=60 -d repeat_for=3600

The answer has the message's id. With the app token in the Authorization header, the app can then:

• GET https://api.bzzd.io/v1/messages/id: whether it was acknowledged (acknowledged_at), and whether it's still repeating.
• POST https://api.bzzd.io/v1/messages/id/stop-repeating: stop the repeats, for example once the problem is fixed.

Images

A JPEG, PNG, WebP or GIF of up to 5 MB, sent as a file in a multipart form, or as base64 text in image (with or without a data:image/…;base64, prefix). It's shown in the notification on Android and desktop, and in the inbox everywhere, scaled to at most 1,280 pixels.

curl https://api.bzzd.io/v1/hooks/APP_TOKEN \
  -F message="Someone is at the door" \
  -F image=@snapshot.jpg

Answers and errors

A message that was accepted answers 200 with its id:

{"id": "0199e3a4-5f7e-7b1e-9c2d-3a4b5c6d7e8f"}

Anything else answers with a list of errors, naming the field when one is wrong:

{"errors": [{"field": "priority", "message": "Use one of: silent, quiet, normal, high, urgent."}]}

401

The app token is missing or not valid.

400

The message can't be delivered: no device can get notifications, or to isn't someone the app reaches.

422

A field is missing or wrong, or the image can't be used.

429

Too many messages: wait the seconds in the Retry-After header, or until next month.

A service event that isn't worth a notification, like a GitHub star, answers {"skipped": true}, so the service doesn't retry it.

Limits

• Each app can send 60 messages a minute.
• Free: 1,000 messages a month per account, kept in the inbox for 7 days.
• Pro: 10,000 messages a month per account, kept in the inbox for 30 days.
• Each copy counts: a message to a shared app with three members counts four times, against the owner's plan.

Coming from Pushover

Tools that only speak Pushover's API can post to bzzd with Pushover's fields (token, user, message, title, url, priority, attachment and the rest) and get Pushover's answer:

Tools with an ntfy or Gotify option work too: see ntfy and Gotify.