A chat PWA can stay useful after the browser tab closes, yet a notification is a promise made by several independent systems: browser permission, a push subscription, a server worker, the device’s notification policy and the user’s own expectations. The MDN Push API reference describes delivery through a service worker; the Notifications API governs how a visible alert is displayed. Neither specification guarantees that each message will reach a person instantly. This runbook tests for the cases that AI-chat demos often omit.

Define a notification contract before writing code

Separate conversation messages, security alerts, creator uploads and optional social suggestions into user-visible categories. For each category record the trigger, allowed sender, retention interval, quiet-hour policy and whether it may expose private text. An incoming chat message should not automatically become a lock-screen transcript. Store a stable event identifier, recipient ID, category and expiration; avoid placing raw private conversation history in a queue. Treat notifications as hints to fetch fresh authorized state, not as an alternative source of truth. Decide up front whether ‘delivered’ means accepted by a push service, displayed by a device or opened by the user. These are different measurements, and mixing them hides real failure rates.

Ask for permission only after a meaningful action

The Notifications API describes an explicit permission step, typically initiated through a user gesture. Show a concise explanation in your own interface first, then offer a voluntary enable button. Never interpret a denied permission as app malfunction or lock the chat experience behind it. Record permission states as unknown, granted or denied without repeatedly nagging users who refuse. Put notification controls near conversation settings, allowing different choices for direct replies and promotional suggestions. On devices where a persistent service-worker notification is necessary, avoid relying on the desktop-only Notification constructor. Test fresh installs, reinstalled PWAs, private browsing restrictions and browsers that do not support a required feature. Fall back to an in-app inbox.

Make the subscription lifecycle explicit

Register a service worker under the intended origin and scope, then subscribe through PushManager after the user authorizes the feature. MDN notes that a PushSubscription contains an endpoint and keys and that the endpoint is a capability URL; handle it as a secret. Do not log full endpoints into analytics dashboards or embed them in screenshots. Bind each subscription to one account, device and generation number; rotate it after logout or reassignment. When a push service reports that a subscription is permanently invalid, mark it stale rather than retrying forever. Store the last verified subscription generation so a delayed device request cannot resurrect a session that the user already removed.

Design small and privacy-safe delivery payloads

Send a generic category and opaque message identifier whenever possible. Fetch the full message only after the user opens the app and the API confirms their current account access. A user might have changed devices, disabled message previews or revoked contact with a sender between queuing and delivery. Encrypt or otherwise protect transport as required by the push service; never assume the push subscription grants authorization to fetch a conversation. Use short time-to-live values for ephemeral chat suggestions, longer ones only for critical account alerts. Map each notification ID to the latest server state and clear a notification when the underlying item is read, withdrawn or expired.

Handle failures without duplicate or misleading alerts

Mobile devices sleep, services throttle, networks disappear and operating systems suppress notifications. Queue sends with a defined retry budget and jitter; retry transient transport failures, but do not resend on every browser reconnect. A useful idempotency key is recipient, event and notification type. Keep one accepted-send record for that combination and a generation counter for re-issued subscriptions. If the user receives the same chat alert twice, inspect send attempts, subscription overlap and client display replacement separately. Show service-accepted, permission-denied and device-unknown as distinct status fields. Never market a push service acknowledgement as proof that a user saw the notification.

Run a cross-device acceptance matrix

Build a test table covering desktop foreground, background tabs, installed PWA, phone locked, device offline, low battery, changed timezone, logout and account switch. On each case capture server event time, first push-service response, visible display when observable, open event and conversation refresh result. For privacy, run tests with synthetic messages and accounts. The pass criteria are no unauthorized preview, no notification after confirmed logout, bounded duplicates and an in-app recovery path. Report delivery under the exact test environment rather than a single global percentage. Include a periodic cleanup of orphaned subscriptions and a manual user control to disable notifications everywhere.

Web push is a useful optional transport, not an engagement mandate. A reliable AI chat service must preserve readable conversation history and user control even when every external alert fails.

Cover photo: Unsplash; illustrative only.

Sources (official materials; accessed 12 November 2026): MDN Push API; MDN Notifications API.