Web Notification Inbox

The web bell + inbox is a drop-in widget for your site. A bell with an unread badge, and an inbox panel: list, read/unread, delete, deep links. It reads the inbox API for one browser device. Plain JS, React and Next.js. No dependencies, no build step.

Quick start — React / Next.js

The widget is three files — native-notify/web/native-notify-bell.js (plain JS), native-notify/web/NativeNotifyBell.jsx (React + the headless hook) and native-notify/web/nativeNotifyBell.css. Drop them into your site, or ask Agent Notify to add the bell to your repo and review the pull request it opens.

// app/site-header.tsx
"use client";

import NativeNotifyBell from "../native-notify/web/NativeNotifyBell";

export function SiteHeader() {
  return (
    <header>
      {/* your header… */}
      <NativeNotifyBell appId={123} webKey="nnweb_…" title="Notifications" />
    </header>
  );
}

Import the stylesheet once for the whole site — in the App Router's root layout (app/layout.tsx), or pages/_app.tsx in the Pages Router:

import "../native-notify/web/nativeNotifyBell.css";

For your own UI instead of the built-in panel, use the headless hook — the same data and actions. It loads nothing on its own: call refresh() for the first page (it also sets unreadCount):

"use client";

import { useEffect } from "react";
import { useNativeNotifyInbox } from "../native-notify/web/NativeNotifyBell";

export function InboxList() {
  const inbox = useNativeNotifyInbox({ appId: 123, webKey: "nnweb_…", take: 20 });
  const { refresh } = inbox;

  // Fetch page 1 — this re-runs once the per-browser device id has resolved.
  useEffect(() => { refresh(); }, [refresh]);

  if (inbox.error) return <p role="alert">{inbox.error}</p>;
  return (
    <ul>
      {inbox.entries.map((entry) => (
        <li key={entry.entryId}>
          <button type="button" onClick={() => inbox.markRead(entry)}>
            {entry.read ? "" : "• "}{entry.title}
          </button>
        </li>
      ))}
    </ul>
  );
}

The hook returns deviceId, entries, total, unreadCount, loading, error and the actions refresh, refreshUnread, markRead(entry), markAllRead, remove(entry), clearInbox and loadMore.

Quick start — plain JS (any site)

<link rel="stylesheet" href="/native-notify/web/nativeNotifyBell.css" />
<script type="module">
  import { mountNativeNotifyBell } from "/native-notify/web/native-notify-bell.js";

  mountNativeNotifyBell({
    appId: window.NN_CONFIG.appId,     // your app id
    webKey: window.NN_CONFIG.webKey,   // the publishable web key — safe in page source
    title: "Notifications",
    position: "bottom-right",          // or mount into your own header
  });
</script>

mount accepts an element or a selector, so the bell can live in your header instead of floating in a corner:

mountNativeNotifyBell({ appId, webKey, mount: "#header-notifications" });

The inbox API behind it

The widget is a thin client of the inbox — one inbox per device, keyed by the same stable deviceId registration uses. All endpoints authenticate with your app id + publishable web key (the web key rides where an app token would go: the GETs carry it in the URL, the POSTs in the body):

The list answers 200 with the device's own entries, newest first:

{
  "ok": true,
  "deviceId": "device-abc",
  "take": 50,
  "skip": 0,
  "total": 12,
  "unread": 3,
  "entries": [
    {
      "entryId": 4181,
      "appId": 123,
      "deviceId": "device-abc",
      "subscriberId": null,
      "environment": "production",
      "title": "New service times",
      "body": "This Sunday: 9am and 11am.",
      "data": { "url": "/news/service-times" },
      "audienceType": "all",
      "source": "api",
      "sentAt": "2026-09-24T14:03:11.000Z",
      "readAt": null,
      "read": false
    }
  ]
}

• take defaults to 50 and must be an integer 1..200 (a larger value is a 400, never a silent cap); skip defaults to 0. total and unread cover the device's whole visible inbox, so "load more" is exact.
• Only the requesting device's own entries are ever returned.
• Every universal send writes one entry per targeted device, in the background — an entry can appear a moment after the send response.

The other calls answer 200 too:

Errors are machine-readable: { "error": { "code", "message", "field"? } } — 400 for missing_field / invalid_field / invalid_device_id / invalid_entry_id / invalid_body, 403 plan_upgrade_required, 404 entry_not_found (an entry that does not exist for this device, or marking a deleted one read) and 404 app_not_found. The owner's side of the same data — every send with read counts, and who is registered — is in the dashboard's Inbox and Audience tabs.

Which deviceId does a browser use?

A browser registers itself as a web device when the site runs the Web Push subscribe snippet. That snippet stores its device id under nn_web_device_id, the same key this widget defaults to — the bell shows exactly the pushes this browser receives. To show the same inbox as your app instead, pass the device id your backend knows for the logged-in user. Plain JS can resolve it with getDeviceId:

mountNativeNotifyBell({
  appId, webKey,
  getDeviceId: async () => (await fetch("/api/me/device-id").then((r) => r.json())).deviceId,
});

The React component and hook take the resolved value as deviceId (there is no getDeviceId prop). The per-browser default id is persisted in localStorage under nn_web_device_id — change the key with storageKey.

Options

The React component takes these as props; the plain-JS mountNativeNotifyBell / createNativeNotifyBell take the same names in their options object.

Deep links

Put a url inside the notification's pushData — the same key the mobile SDKs use (see Push Data & Taps):

{
  "title": "New service times",
  "message": "This Sunday: 9am and 11am.",
  "pushData": { "url": "/news/service-times" }
}

Clicking the row marks it read and then opens the URL — same-origin paths and http(s) URLs only; anything else is ignored. Pass onNavigate when your app prefers client-side routing.

The credential on the client

The widget calls the API from the browser, so its credential is visible in your page — that is exactly why the publishable web key exists: it can only register/deregister one browser device and read or mark that device's own inbox. It can never send, list groups or subscribers, or touch another device. Read it on the dashboard under App Settings → App keys, or:

GET https://app.nativenotify.com/api/apps/<APP_ID>/web-key

If your policy requires even the web key to stay server-side, proxy the six calls above through your own API — the widget accepts apiBase. Full details: App Keys & Token Rotation.