🌐 Send Web Push Notifications
Web Push Notifications allow you to display native-like notifications to users through your website/web app, even when they’re not on your website.
Pros:
- Native-like notifications
- No need to install a full-fledged app
Cons:
- Requires explicit user opt-in
- Apple is not a fan of web push notifications
Supported Browsers
Browser | Windows | macOS | Linux | Android | iOS/iPadOS | ChromeOS | Notes |
---|---|---|---|---|---|---|---|
Google Chrome | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | |
Mozilla Firefox | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | |
Apple Safari | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | |
Microsoft Edge | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | |
Opera | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | |
Brave | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | Requires enabling “Use Google services for push messaging”. |
Samsung Internet | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | |
Platform Notes | May require allowing notifications in system settings | Safari: on iOS/iPadOS 16.4+, requires PWA installation. |
Overview
Web push notifications rely on a service worker, a script that runs in the background of a user’s browser. This allows it to receive and display notifications even when your website isn’t open.
When a user grants permission for notifications, the service worker is registered, and a unique push subscription is created for them. This subscription acts as the address for sending notifications.
The process also involves VAPID (Voluntary Application Server Identification) keys. These keys securely identify your application to the browser’s push service, ensuring that notifications are coming from a legitimate source.
NotificationAPI abstracts away all this complexity. Our SDKs handle the service worker, manage push subscriptions, and secure communications with VAPID keys automatically.
The setup process looks like this:
- Create NotificationAPI Account
- Implement the Frontend SDK
- Set Up the Service Worker
- Request and Provide Permission
- Send Notifications from the Backend
1. Create NotificationAPI Account
Make sure you have a NotificationAPI account and grab your Client ID.
2. Implement the Frontend SDK
Our front-end SDKs will handle requesting user permission, syncing
Install the SDK:
npm install @notificationapi/react --legacy-peer-deps
# or
# yarn add @notificationapi/react
# or
# pnpm add @notificationapi/react
Then in your router, you can use the provider to request notification permission.
import { NotificationAPIProvider } from '@notificationapi/react';
<App>
<NotificationAPIProvider
clientId="abc123"
userId="user@example.com"
customServiceWorkerPath="service/notificationapi-service-worker.js"
>
{/* routes where you want to request notification permission */}
</NotificationAPIProvider>
</App>;
Parameters
Parameter | Type | Description |
---|---|---|
clientId* | string | Your NotificationAPI account clientId. You can get it from here. |
userId* | string | The unique ID of the user in your system. |
webPushOptInMessage | boolean | Whether to request notification permission automatically. Default is true. |
customServiceWorkerPath | string | If your service worker is not accessible at {website}/notificationapi-service-worker.js, specify the path here, relative to the website domain/root. E.g. /service/myworker.js |
For more information please checkout our React SDK guide.
3. Set up Service Worker
The service worker manages background tasks and is essential for receiving push notifications. It should be publicly accessible, so it usually goes in the public
folder of your web application.
- Download notificationapi-service-worker.js
- Place the file in the
public
folder of your web application. It should be accessible athttps://yourdomain.com/notificationapi-service-worker.js
.
If the service worker is not at {website}/notificationapi-service-worker.js, specify its path using the customServiceWorkerPath
parameter during SDK initialization.
For example, if service worker accessible at https://yourdomain.com/service/myworker.js
, then the customServiceWorkerPath should be /service/myworker.js
.
4. Request and Provide Permission
With our SDK and service worker in place, the notifications are ready to flow, however, you need to get the user’s permission.
There are multiple options to prompt the user for permissions:
Option 1: Programmatically
You can use NotificationAPIContext
and the setWebPushOptIn
method to programmatically request permission.
const AskforPerm: React.FC = () => {
const notificationapi = NotificationAPIProvider.useNotificationAPIContext();
return (
<Button
onClick={() => {
notificationapi.setWebPushOptIn(true);
}}
>
Click to pop up the permission prompt
</Button>
);
};
export default AskforPerm;
Option 2: Pre-built UIs
If you are using our pre-built React UIs, it will automatically display an opt-in message inside the in-app notifications screen and the user preference screen.


5. Trigger Notifications from the Backend
Given the frontend is set up to receive notifications and the user has granted permission, you can now trigger them from your backend.
Ensure that the userId used to trigger the notification is the same as the userId used to initialize the frontend SDK.
Schematic Diagram
Below is a detailed schematic that breaks down each step:
Frequently Asked Questions (FAQs)
Why I see this message: WEB_PUSH delivery is activated, but the user’s webPushTokens is not provided. Discarding WEB_PUSH?
It means that you have done Step 1 and Step 5 correctly, but you probably have not implemented our frontend SDK correctly (Step 2), or you have not set up the service worker (Step 3), or your user is not opted in for receiving web push notification (Step 4).
Why can I not see the browser prompt in Step 4?
If you do not see the message in the NotificationAPI component, that browser has already opted in for that user.
Reset Chrome on Desktop
- Click the “View Site Information” icon next to your URL in the Chrome browser.
- Under “Notifications”, click the Reset permission button.
Reset Firefox on Desktop
- Click the “i” or “lock” icon beside your site URL.
- Next to Receive Notifications under Permissions, select the “X” button next to Allowed
How can I make sure if the Service Worker has been initialized properly?
-
Follow the Step 3
-
Open the built-in developer tools for the site (F12 on PC or fn + F12 on Mac), then go to Applications >> Service workers. If the service worker has been initialized, it would look something like this:

- If notificationapi-service-worker.js (Service Worker) doesn’t show up, that means the service worker is not there inside the public folder. Please make sure that it is placed inside the public folder. Or pass the address to the publicly available file using
customServiceWorkerPath
How to check Notification Settings on macOS and Windows?
It’s important to verify your notification settings at your operating system level as well to ensure proper functionality.
macOS
- Go to System Preferences > Notifications.
- Find your app (chrome, firefox, safari, etc…) in the list and ensure notifications are enabled.

Windows
- Open Settings > System > Notifications.
- Ensure to enable Notifications for proper functionality.
