2.2 KiB
NIP-97
Push Notification Event Watcher API
draft optional
This NIP defines a common API to register push notification tokens into one or more event watch servers, which constantly query several relays to notify users on new events.
The goal is to allow users to choose their event watch servers by simply adding an http address to their account.
Registration Call
After receiving a token from the push system (Google Services, Unified Push, Apple Push Notification), clients should upload a list of signed NIP-98 events, one for each account in the device, in a POST to /register with the following body:
{
"events": [
{
"id": "..",
"pubkey": "...",
"created_at": ...,
"kind": 22242,
"tags":[
[ "relay","<inbox relay 1>" ],
[ "relay","<inbox relay 2>" ],
[ "challenge", "<system>:<token>" ]
],
"content":"",
"sig":"..."
}
]
}
where system is google, apple or unifiedpush.
Servers will use the system information to select where to send new events from the relays marked as such.
The server returns with an array of
[
{
"pubkey": "<pubkey>",
"result": "<added|replaced|error>",
"error": "<message>",
}
]
Servers SHOULD accept multiple tokens per pubkey, but may limit the number of them.
Servers SHOULD delete tokens after failure to deliver.
Sending Events
Servers send new events as stringified JSONs in the user's preferred system.
The event MUST be NIP-59 GiftWrapped to the receiver. But since it already goes to the destination via the token, no p-tag is added to the wrap event. In this way, the chosen system cannot know which key is receiving a notification.
Clients SHOULD decrypt the GiftWrap with all logged-in accounts to find the user this event is for.
Event Watcher list
An Event Watcher list is a kind 10097 replaceable event meant to select one or more servers the user wants to register for push notifications. Servers are listed as server tags:
{
"kind": 10097,
"content": "",
"tags": [
["server", "https://push.amethyst.social"],
["server", "https://server2.com"],
]
}