NIP-46

Notifiers

A notifier is a nostr application whose job is to monitor the nostr network and notify users of updates via email, push, SMS, DM, etc.

Notification Subscription

A notification subscription is a kind 32830 event which specifies how a user would like to be notified, and by whom. It MUST have the following tags, and no others:

A d tag set to an arbitrary string
A p tag indicating the notifier the subscription is addressed to

All other tags MUST be encrypted to the pubkey indicated by the p tag using NIP 44. The following tags are defined:

channel indicates how the user would like to be notified. May be one of email, push
relay (one or more) indicates relays where notifications may be discovered
filter (one or more) indicates a filter matching events that the user wants to be notified about
cadence (optional) indicates (roughly) how often the user would like to be notified. May be one of weekly, daily, immediate
bunker_url (optional) with permission to sign kind 22242 AUTH requests (for access to auth-gated relays)
pause_until (optional) indicates how long the notifier should wait from the event's created_at before sending immediate mode notifications.

If channel is set to push, the following tags are also required:

token indicates a push notification token
platform indicates the user's app platform (ios|android|web)

If channel is set to email, the following tags are also required:

email indicates the user's email address

Unsubscribing

When a user no longer wants to be notified, they may delete the subscription event by address following NIP 09.

Pausing while online

When a user becomes active, their client SHOULD automatically update all relevant kind 32930 events with a current pause_until timestamp. This allows the notifier to know the user is online and avoid sending push notifications. When a client knows it's about to go offline, it MAY update the pause_until timestamp to the current time.

Example

Below is an example tag array (the entire event is not shown because the tags are encrypted and placed in content).

[
  ["channel", "email"],
  ["cadence", "weekly"],
  ["bunker_url", "bunker://9ee57420bac3db5f1d7f43e1ed5f8bb6b81bf6df6350eb3377961da229eaab22?relay=wss://r.example.com&secret=9393"],
  ["pause_until", "1740002930"],
  ["relay", "wss://relay1.example.com/"],
  ["relay", "wss://relay2.example.com/"],
  ["filter", "{\"#p\":[\"c90b4e622a3a5c38aebd5ba3cbb22e4ab5a20056b499f8d2e3d25ff47f589a6b\"]}"],
  ["filter", "{\"#h\":[\"b3ce4a9f\"]}"],
  ["email", "email@example.com"]
]

Notification Subscription Status

A notifier SHOULD publish a kind 32831 event which details the status of the user's subscription. A non-existent subscription event indicates that no action has been taken. It MUST have the following tags, and no others:

An a tag set to the address of the kind 32830 it refers to
A p tag indicating the notifier the subscription is addressed to

All other tags MUST be encrypted to the pubkey indicated by the p tag using NIP 44. The following tags are defined:

status SHOULD be one of ok, payment-required, error
message SHOULD include human-readable information explaining the status of the subscription

Discovery

A notifier MAY advertise its services via NIP 89 client listing.

3.4 KiB Raw Blame History