Web notification inbox

Add the bell

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

// 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 "../native-notify/web/nativeNotifyBell.css";

<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>

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

Build your own UI

The headless hook returns the same data and actions. It loads the unread count itself — call refresh() for the first page of entries:

"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>
  );
}

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

Choose the device

The bell shows one device's inbox — by default this browser's, whose id lives in localStorage under nn_web_device_id, the key the web push snippet registers under. To show another device, pass its id; plain JS resolves it with getDeviceId:

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

The web key reads only devices it registered, so a native device answers 403 web_key_scope.

Options

React takes these as props. Plain JS (mountNativeNotifyBell, createNativeNotifyBell) takes the same names as options.

Deep links

Put a url in the send's pushData:

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

A click marks the row read, then opens the URL. Only same-origin paths and http(s) URLs open; anything else is ignored. Pass onNavigate to route client-side.

The inbox API

The widget calls the six inbox endpoints with the web key where an app token would go — in the URL for GETs, in the body for POSTs. Your side of the same data — every send with its read counts, and who is registered — is in the dashboard's Inbox and Audience tabs.

A browser that hasn't registered with the web key answers 403 web_key_scope; the widget shows an empty inbox. Every other code is in Mobile notification inbox.

The web key

The widget's credential is visible in your page, so it uses the publishable web key: it can register one browser device and read or mark that device's own inbox — never send, list groups or subscribers, or touch another device. Copy it from App Settings → App keys, or read it with a dashboard session or MCP token:

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

To keep even the web key out of your page, proxy the six calls through your own API and set apiBase. See App keys & token rotation.