Feature Guide

Push Notifications

Web Push notifications allow Org Comms to re-engage members even when the application isn't open. Using Service Workers and VAPID keys, you can deliver real-time alerts to desktop and mobile devices.

How it works

VAPID Security

VAPID (Voluntary Application Server Identification) keys authenticate your server with the push delivery service, preventing unauthorized notifications. Generate them once with npx web-push generate-vapid-keys and add them to your Convex environment.

Service Workers

The Service Worker at public/sw.js runs in the background, listens for push events, and displays the notification — even when the main browser tab is closed.

The delivery flow

From admin action to device notification — four steps handled entirely by Org Comms and Convex.

Push Notification Flow
✉️
Admin sends message
⚡
Convex triggers push
🌐
Push service delivers
🔔
Service Worker shows alert
Org Comms
Q3 Town Hall — Save the date
now

The Implementation Chain

1

User Permission

Modern browsers require a manual user gesture to request notification permissions. This is why Org Comms includes an 'Enable Alerts' button.

2

Subscription Creation

Once permitted, the browser generates a unique endpoint and cryptographic keys for that specific browser instance.

3

Secure Storage

Subscriptions are stored in Convex linked to the user account, enabling targeted broadcasts without managing complex infrastructure.

4

Broadcast Delivery

When an admin sends a message, an internal Node.js action in Convex triggers the web-push protocol to reach the user.

Optimising for Mobile (PWA)

For a native-like notification experience on iOS and Android, it is highly recommended to install the application as a PWA from the browser's "Add to Home Screen" option.

  • Persistence: PWA apps maintain background sync more reliably than browser tabs.
  • Badging: App icon badges can reflect the number of unread messages.
  • Trust: Home screen apps usually have higher notification permission retention rates.

Setting up push notifications

1

Generate VAPID keys

Run npx web-push generate-vapid-keys to generate your public/private VAPID key pair.

2

Add keys to environment

Set VITE_VAPID_PUBLIC_KEY in .env.local and VAPID_PUBLIC_KEY + VAPID_PRIVATE_KEY in the Convex dashboard using npx convex env set.

3

Enable alerts in the app

After signing in, navigate to the Messages page and click 'Enable Alerts'. Grant notification permission in the browser prompt.

4

Send a test message

As an admin, send a broadcast message. The recipient should receive a browser/device notification within seconds.

Frequently Asked Questions

Why do users need to click 'Enable Alerts' before receiving push notifications?

Modern browsers require an explicit user gesture to request notification permissions. This is a browser security requirement, not an Org Comms limitation. Automatically requesting permission on page load is blocked by browsers and would likely be denied by users.

Do push notifications work when the browser is completely closed?

On desktop browsers, the browser process typically needs to be running (even in the background) for push notifications to arrive. On mobile, installing the app as a PWA gives you the most reliable background notification delivery.

Does Org Comms support push notifications on iOS?

Yes, via the PWA. iOS 16.4+ supports Web Push for installed PWAs. Users must add the app to their Home Screen via Safari's 'Add to Home Screen' option to receive push notifications.

What happens if a push notification fails to deliver?

If the push service returns an error (e.g. the subscription has expired), the delivery record is still created for the inbox message. The push failure is logged but does not prevent the message from appearing in the member's inbox.

Can members control which types of notifications they receive?

Yes. Members can set their push preference to 'all' (receive all messages), 'urgent' (only high-priority messages), or 'none' (disable push). This preference is stored in the pushSubscriptions table.

Do I need a separate paid notification service?

No. Org Comms uses the Web Push protocol directly via the open-source web-push npm package. There is no third-party notification service required — notifications are delivered through the browser's native push infrastructure (operated by browser vendors).