NotificationService
Push notifications: this device's Web Push subscription, what pushes, quiet hours and a test notification.
On this page
- Summary
- Methods
- GetPushConfig
- SubscribePush
- UnsubscribePush
- RenewPushSubscription
- ListPushSubscriptions
- GetNotificationSettings
- UpdateNotificationSettings
- SetGroupPush
- SendTestPush
- Types
- GetNotificationSettingsRequest
- GetPushConfigRequest
- ListPushSubscriptionsRequest
- ListPushSubscriptionsResponse
- NotificationSettings
- PushConfig
- PushSubscription
- RenewPushSubscriptionRequest
- RenewPushSubscriptionResponse
- SendTestPushRequest
- SendTestPushResponse
- SetGroupPushRequest
- SubscribePushRequest
- UnsubscribePushRequest
- UnsubscribePushResponse
- UpdateNotificationSettingsRequest
- See also
Push notifications: standard Web Push (RFC 8030) to the browser's own push service, the payload encrypted to the browser (RFC 8291, aes128gcm) and signed with the platform's VAPID key (RFC 8292). No paid push service: the browsers' own (Google's FCM endpoint for Chrome, Mozilla's autopush for Firefox, Apple's for Safari, WNS for Edge) carry the encrypted bytes and can't read them. What pushes: direct messages, friend requests, party invites, game invites and group announcements, each with its own switch, only to an account that isn't connected to the realtime gateway right now (an open app shows the in-app toast instead), never from someone the recipient blocked or muted, and not during the recipient's quiet hours. A device's subscriptions go when it's signed out; a push service saying an endpoint is gone (404, 410) removes it. The service worker (apps/web/public/sw.js) receives the decrypted JSON payload: {"kind": "dm"|"friend_request"|"party_invite"|"game_invite"|"group_announcement"|"test", "title", "body", "url" (a path on the web app), "tag" (notifications with one tag replace each other), "sentAt"} Every method is a POST with a JSON body; see the overview for the protocol, authentication and errors.
Summary#
| Method | Auth | Description |
|---|---|---|
| GetPushConfig | None | The platform's VAPID public key (the browser's applicationServerKey). Anyone may ask. |
| SubscribePush | Account | Registers this browser's push subscription for the caller (PushSubscription.toJSON()). The same endpoint again updates it; an endpoint another account registered moves to the caller (one browser, one signed-in account). |
| UnsubscribePush | Account | Removes a subscription by its endpoint or its id (psh_...). Removing one that's already gone succeeds. |
| RenewPushSubscription | None | The browser's push service replaced a subscription (the service worker's pushsubscriptionchange event, which has no access token): the old endpoint, which only that browser knows, authorizes moving the registration to the new one. No token needed. |
| ListPushSubscriptions | Account | The caller's registered devices. |
| GetNotificationSettings | Account | |
| UpdateNotificationSettings | Account | Changes what pushes (unset fields keep their value). |
| SetGroupPush | Account | Turns a group's announcement pushes off or on for the caller (a member). |
| SendTestPush | Account | Sends a test notification to every device of the caller's (or the one named), now, whatever the quiet hours say. A few per 10 minutes. |
Methods#
GetPushConfig#
The platform's VAPID public key (the browser's applicationServerKey). Anyone may ask.
POST /neo.platform.v1.NotificationService/GetPushConfig
Content-Type: application/jsonAuth: None.
Request: GetPushConfigRequest. Response: PushConfig.
SubscribePush#
Registers this browser's push subscription for the caller (PushSubscription.toJSON()). The same endpoint again updates it; an endpoint another account registered moves to the caller (one browser, one signed-in account).
POST /neo.platform.v1.NotificationService/SubscribePush
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: SubscribePushRequest. Response: PushSubscription.
UnsubscribePush#
Removes a subscription by its endpoint or its id (psh_...). Removing one that's already gone succeeds.
POST /neo.platform.v1.NotificationService/UnsubscribePush
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: UnsubscribePushRequest. Response: UnsubscribePushResponse.
RenewPushSubscription#
The browser's push service replaced a subscription (the service worker's pushsubscriptionchange event, which has no access token): the old endpoint, which only that browser knows, authorizes moving the registration to the new one. No token needed.
POST /neo.platform.v1.NotificationService/RenewPushSubscription
Content-Type: application/jsonAuth: None.
Request: RenewPushSubscriptionRequest. Response: RenewPushSubscriptionResponse.
ListPushSubscriptions#
The caller's registered devices.
POST /neo.platform.v1.NotificationService/ListPushSubscriptions
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: ListPushSubscriptionsRequest. Response: ListPushSubscriptionsResponse.
GetNotificationSettings#
POST /neo.platform.v1.NotificationService/GetNotificationSettings
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: GetNotificationSettingsRequest. Response: NotificationSettings.
UpdateNotificationSettings#
Changes what pushes (unset fields keep their value).
POST /neo.platform.v1.NotificationService/UpdateNotificationSettings
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: UpdateNotificationSettingsRequest. Response: NotificationSettings.
SetGroupPush#
Turns a group's announcement pushes off or on for the caller (a member).
POST /neo.platform.v1.NotificationService/SetGroupPush
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: SetGroupPushRequest. Response: NotificationSettings.
SendTestPush#
Sends a test notification to every device of the caller's (or the one named), now, whatever the quiet hours say. A few per 10 minutes.
POST /neo.platform.v1.NotificationService/SendTestPush
Content-Type: application/jsonAuth: A signed-in account. Guests are refused.
Request: SendTestPushRequest. Response: SendTestPushResponse.
Types#
GetNotificationSettingsRequest#
No fields: send {}.
GetPushConfigRequest#
No fields: send {}.
ListPushSubscriptionsRequest#
No fields: send {}.
ListPushSubscriptionsResponse#
| Field | Type | Description |
|---|---|---|
subscriptions | array of PushSubscription |
NotificationSettings#
| Field | Type | Description |
|---|---|---|
pushDms | boolean | Per kind (all on by default). |
pushFriendRequests | boolean | |
pushPartyInvites | boolean | |
pushGameInvites | boolean | |
pushGroupAnnouncements | boolean | |
pushPreviews | boolean | Message text in the notification (off: "New message from <name>" only, for lock screens). |
quietHours | boolean | No pushes between quiet_start and quiet_end (minutes after midnight, 0-1439, in time_zone; start > end wraps past midnight). |
quietStart | number | |
quietEnd | number | |
timeZone | string | An IANA time zone (Europe/Berlin); the browser's by default. |
mutedGroupIds | array of string | Groups whose announcements don't push (grp_...). |
pushAvailable | boolean | Whether the server can push at all (it has a VAPID key). |
quietNow | boolean | Whether it's quiet hours for the caller right now. |
PushConfig#
| Field | Type | Description |
|---|---|---|
enabled | boolean | false: this server has no VAPID key (deploy/secrets.sh makes one), so nothing pushes |
vapidPublicKey | string | The uncompressed P-256 public key, base64url without padding (65 bytes). |
PushSubscription#
| Field | Type | Description |
|---|---|---|
id | string | psh_... |
label | string | What the device is ("Web - Chrome on macOS"), from the client's x-neo-client header. |
service | string | The push service's host (fcm.googleapis.com, updates.push.services.mozilla.com...). |
createdAt | string | |
lastSuccessAt | string | The last push the service accepted; empty: none yet. |
failures | number | Failed deliveries in a row (the subscription goes after 10, or at once on 404 / 410). |
thisDevice | boolean | Whether it's the device this call came from. |
RenewPushSubscriptionRequest#
| Field | Type | Description |
|---|---|---|
oldEndpoint | string | |
endpoint | string | |
p256dh | string | |
auth | string | |
expirationTime | string (int64) |
RenewPushSubscriptionResponse#
| Field | Type | Description |
|---|---|---|
renewed | boolean |
SendTestPushRequest#
| Field | Type | Description |
|---|---|---|
subscriptionId | string | psh_...; empty: every device |
SendTestPushResponse#
| Field | Type | Description |
|---|---|---|
queued | number | Pushes queued (one per device). |
SetGroupPushRequest#
| Field | Type | Description |
|---|---|---|
groupId | string | |
enabled | boolean |
SubscribePushRequest#
| Field | Type | Description |
|---|---|---|
endpoint | string | PushSubscription.endpoint: an https URL of a known push service. |
p256dh | string | PushSubscription.toJSON().keys: p256dh (the browser's P-256 key, base64url) and auth (16 bytes, base64url). |
auth | string | |
expirationTime | string (int64) | PushSubscription.expirationTime (epoch milliseconds); 0: none. |
UnsubscribePushRequest#
| Field | Type | Description |
|---|---|---|
endpoint | string | |
subscriptionId | string |
UnsubscribePushResponse#
| Field | Type | Description |
|---|---|---|
removed | boolean |
UpdateNotificationSettingsRequest#
| Field | Type | Description |
|---|---|---|
pushDms | boolean, optional | |
pushFriendRequests | boolean, optional | |
pushPartyInvites | boolean, optional | |
pushGameInvites | boolean, optional | |
pushGroupAnnouncements | boolean, optional | |
pushPreviews | boolean, optional | |
quietHours | boolean, optional | |
quietStart | number, optional | |
quietEnd | number, optional | |
timeZone | string, optional |