mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-22 16:35:52 -05:00
79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
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](98.md) events, one for each account in the device, in a `POST` to `/register` with the following body:
|
|
|
|
```jsonc
|
|
{
|
|
"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
|
|
|
|
```jsonc
|
|
[
|
|
{
|
|
"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](59.md) 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:
|
|
|
|
```json
|
|
{
|
|
"kind": 10097,
|
|
"content": "",
|
|
"tags": [
|
|
["server", "https://push.amethyst.social"],
|
|
["server", "https://server2.com"],
|
|
]
|
|
}
|
|
```
|