NEOLearn

NotificationService

Push notifications: this device's Web Push subscription, what pushes, quiet hours and a test notification.

Updated October 21, 2026

On this page

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#

MethodAuthDescription
GetPushConfigNoneThe platform's VAPID public key (the browser's applicationServerKey). Anyone may ask.
SubscribePushAccountRegisters 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).
UnsubscribePushAccountRemoves a subscription by its endpoint or its id (psh_...). Removing one that's already gone succeeds.
RenewPushSubscriptionNoneThe 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.
ListPushSubscriptionsAccountThe caller's registered devices.
GetNotificationSettingsAccount
UpdateNotificationSettingsAccountChanges what pushes (unset fields keep their value).
SetGroupPushAccountTurns a group's announcement pushes off or on for the caller (a member).
SendTestPushAccountSends 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.

HTTP
POST /neo.platform.v1.NotificationService/GetPushConfig
Content-Type: application/json

Auth: 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).

HTTP
POST /neo.platform.v1.NotificationService/SubscribePush
Content-Type: application/json

Auth: 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.

HTTP
POST /neo.platform.v1.NotificationService/UnsubscribePush
Content-Type: application/json

Auth: 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.

HTTP
POST /neo.platform.v1.NotificationService/RenewPushSubscription
Content-Type: application/json

Auth: None.

Request: RenewPushSubscriptionRequest. Response: RenewPushSubscriptionResponse.

ListPushSubscriptions#

The caller's registered devices.

HTTP
POST /neo.platform.v1.NotificationService/ListPushSubscriptions
Content-Type: application/json

Auth: A signed-in account. Guests are refused.

Request: ListPushSubscriptionsRequest. Response: ListPushSubscriptionsResponse.

GetNotificationSettings#

HTTP
POST /neo.platform.v1.NotificationService/GetNotificationSettings
Content-Type: application/json

Auth: A signed-in account. Guests are refused.

Request: GetNotificationSettingsRequest. Response: NotificationSettings.

UpdateNotificationSettings#

Changes what pushes (unset fields keep their value).

HTTP
POST /neo.platform.v1.NotificationService/UpdateNotificationSettings
Content-Type: application/json

Auth: 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).

HTTP
POST /neo.platform.v1.NotificationService/SetGroupPush
Content-Type: application/json

Auth: 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.

HTTP
POST /neo.platform.v1.NotificationService/SendTestPush
Content-Type: application/json

Auth: 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#

FieldTypeDescription
subscriptionsarray of PushSubscription

NotificationSettings#

FieldTypeDescription
pushDmsbooleanPer kind (all on by default).
pushFriendRequestsboolean
pushPartyInvitesboolean
pushGameInvitesboolean
pushGroupAnnouncementsboolean
pushPreviewsbooleanMessage text in the notification (off: "New message from <name>" only, for lock screens).
quietHoursbooleanNo pushes between quiet_start and quiet_end (minutes after midnight, 0-1439, in time_zone; start > end wraps past midnight).
quietStartnumber
quietEndnumber
timeZonestringAn IANA time zone (Europe/Berlin); the browser's by default.
mutedGroupIdsarray of stringGroups whose announcements don't push (grp_...).
pushAvailablebooleanWhether the server can push at all (it has a VAPID key).
quietNowbooleanWhether it's quiet hours for the caller right now.

PushConfig#

FieldTypeDescription
enabledbooleanfalse: this server has no VAPID key (deploy/secrets.sh makes one), so nothing pushes
vapidPublicKeystringThe uncompressed P-256 public key, base64url without padding (65 bytes).

PushSubscription#

FieldTypeDescription
idstringpsh_...
labelstringWhat the device is ("Web - Chrome on macOS"), from the client's x-neo-client header.
servicestringThe push service's host (fcm.googleapis.com, updates.push.services.mozilla.com...).
createdAtstring
lastSuccessAtstringThe last push the service accepted; empty: none yet.
failuresnumberFailed deliveries in a row (the subscription goes after 10, or at once on 404 / 410).
thisDevicebooleanWhether it's the device this call came from.

RenewPushSubscriptionRequest#

FieldTypeDescription
oldEndpointstring
endpointstring
p256dhstring
authstring
expirationTimestring (int64)

RenewPushSubscriptionResponse#

FieldTypeDescription
renewedboolean

SendTestPushRequest#

FieldTypeDescription
subscriptionIdstringpsh_...; empty: every device

SendTestPushResponse#

FieldTypeDescription
queuednumberPushes queued (one per device).

SetGroupPushRequest#

FieldTypeDescription
groupIdstring
enabledboolean

SubscribePushRequest#

FieldTypeDescription
endpointstringPushSubscription.endpoint: an https URL of a known push service.
p256dhstringPushSubscription.toJSON().keys: p256dh (the browser's P-256 key, base64url) and auth (16 bytes, base64url).
authstring
expirationTimestring (int64)PushSubscription.expirationTime (epoch milliseconds); 0: none.

UnsubscribePushRequest#

FieldTypeDescription
endpointstring
subscriptionIdstring

UnsubscribePushResponse#

FieldTypeDescription
removedboolean

UpdateNotificationSettingsRequest#

FieldTypeDescription
pushDmsboolean, optional
pushFriendRequestsboolean, optional
pushPartyInvitesboolean, optional
pushGameInvitesboolean, optional
pushGroupAnnouncementsboolean, optional
pushPreviewsboolean, optional
quietHoursboolean, optional
quietStartnumber, optional
quietEndnumber, optional
timeZonestring, optional

See also#