beeper-inbox-react

React embeddable inbox widget for Beeper.

The widget resolves the realtime Convex backend from Beeper's /widget/config endpoint. Host apps do not pass a convexUrl.

Public API

Most host apps only need:

• projectId
• publishableKey
• subscriber

By default the provider talks to the hosted Beeper API — the origin is built into the package, so you do not need to know or configure it.

You only need baseUrl if you are overriding the API origin for local development, staging, or self-hosted routing.

Advanced: baseUrl override

The provider talks to two origins:

| What | URL | Purpose | |------|-----|--------| | Beeper Widget API | Defaults to the hosted Beeper API origin | GET/POST …/api/v1/projects/:id/widget/... (inbox, config, read, etc.) | | Session mint (default) | Your app origin, e.g. http://localhost:3001 | POST /api/beeper/widget-session — mints short-lived widget sessions using your server key |

If you override baseUrl, it must be an origin serving Beeper widget REST routes.

In this repo’s current backend architecture, that override points at the Convex HTTP deployment (…convex.site) and must support CORS preflight on /api/v1/.

Why POST /api/beeper/widget-session runs often

That call mints the short-lived x-beeper-session-token. It runs when there is no token yet, before inbox/read actions, and when refreshing an expiring session. If it runs in a tight loop, the mint endpoint is probably failing (check 503 / JSON error and server env BEEPER_SERVER_KEY, CONVEX_SITE_URL).

Install

pnpm add beeper-inbox-react beeper-sdk

Host backend session mint

Use beeper-sdk on your backend (never browser):

import { BeeperClient } from "beeper-sdk";

const beeper = new BeeperClient({
  projectId: process.env.BEEPER_PROJECT_ID!,
  apiKey: process.env.BEEPER_SERVER_KEY!,
});

export async function createWidgetSession(subscriberId: string) {
  return beeper.createWidgetSession({
    subscriberId,
    profile: {
      displayName: "John Doe",
      email: "[email protected]",
    },
  });
}

// Optional: revoke active widget sessions (all or by subscriberId)
export async function revokeWidgetSessions(subscriberId?: string) {
  return beeper.revokeWidgetSessions({ subscriberId });
}

Frontend usage

import {
  BeeperInboxProvider,
  BeeperInboxBell,
  BeeperInboxPanel,
} from "beeper-inbox-react";

function App() {
  return (
    <BeeperInboxProvider
      projectId={import.meta.env.VITE_BEEPER_PROJECT_ID}
      publishableKey={import.meta.env.VITE_BEEPER_PUBLISHABLE_KEY}
      subscriber={{ subscriberId: "user_123" }}
      theme="system"
      customization={{
        accentColor: "#f97316",
        headerTitle: "Notifications",
      }}
      onEvent={(event) => {
        // Hook into your telemetry pipeline.
        // Example events: session.refresh.error, realtime.error, api.error
        console.debug("[beeper-widget-event]", event);
      }}
    >
      <BeeperInboxBell />
      <BeeperInboxPanel />
    </BeeperInboxProvider>
  );
}

Advanced override example:

<BeeperInboxProvider
  projectId="your-project-id"
  publishableKey="your-publishable-key"
  subscriber={{ subscriberId: "user_123" }}
>
  <BeeperInboxBell />
  <BeeperInboxPanel />
</BeeperInboxProvider>

By default, the provider calls POST /api/beeper/widget-session on the same origin as the page (resolved with new URL(sessionEndpoint, window.location.origin)), with a JSON body:

{ projectId, subscriberId, profile }

Your backend should mint a token with the server API key and return either { widgetSessionToken } or { data: { widgetSessionToken } } (matching the Beeper REST shape).

The minted token is kept in sessionStorage for that project and subscriber and reused on later page loads in the same tab until it is about to expire, so a reload doesn't mint a new session. It never outlives the tab. Pass persistSession={false} to mint on every load instead. A token passed as sessionToken is used as given and never stored. The widget config (look and feel from the dashboard) is reused the same way for up to 10 minutes.

Beeper web app (apps/web)

The Beeper dashboard mints sessions for its own inbox at POST /api/internal/inbox-session (named so it is not confused with the /api/beeper/widget-session route you build in your app). It serves only the dashboard's own project. Configure server env:

• BEEPER_SERVER_KEY — project API key with widget:session:create or ingest:write
• BEEPER_PROJECT_ID (or VITE_BEEPER_PROJECT_ID) — the project it mints for; the request body is ignored
• CONVEX_SITE_URL or VITE_CONVEX_SITE_URL — only needed by the server-side session proxy in this repo

BeeperInboxBell

• Default: bell icon + unread badge.
• variant="minimal" restores the text + count pill.
• renderTrigger={({ toggle, unreadCount, open, triggerRef }) => <button ref={triggerRef}>…</button>} — attach triggerRef so the panel can anchor correctly.

If your host app needs custom session behavior, use getSessionToken or sessionEndpoint.

Tabs, per-tab badges and dismiss

Pass tabs to split the panel by metadata.kind. A tab without kind shows everything. Each tab's badge counts its kinds' unread items. The counts come back with the inbox request, so they add no requests of their own:

<BeeperInboxProvider
  {...props}
  tabs={[
    { key: "all", label: "Tout" },
    { key: "orders", label: "Kòmand", kind: "order" },
    { key: "messages", label: "Mesaj", kind: ["chat", "review"] },
  ]}
  defaultTab="all"
  customization={{ showDismiss: true }}
>

• The tabs are hidden when customization.showTopicTabs is false.
• showDismiss adds a Dismiss button that archives the item. It leaves the list at once, counts as read, and comes back if the request fails. It's off by default.
• useBeeperInbox() exposes activeTab, setActiveTab, tabUnreadCount(tab), unreadByKind, archive(id) and unarchive(id) for a custom UI.

What loads when

While the panel is closed, the provider keeps only the unread counts current (one small read). The list loads when the panel opens, 20 items at a time, with a Show older button for the rest (hasMore, loadingMore and loadMore() in useBeeperInbox()).

A component calling useBeeperInbox() keeps the list loaded while it is mounted, so a custom panel gets items as before. For a custom badge, use useBeeperInboxUnreadCount(), which reads only unreadCount, unreadByKind and tabUnreadCount and doesn't load the list.

Web push token registration (FCM)

After you obtain an FCM token in your app, pass it to the provider so the widget registers it automatically:

<BeeperInboxProvider
  {...props}
  push={{
    token: fcmToken,
    platform: "web",
    deviceLabel: "chrome-main",
    autoRegister: true,
    autoUnregister: false,
  }}
>
  <BeeperInboxBell />
  <BeeperInboxPanel />
</BeeperInboxProvider>

Manual registration is also available:

const { registerPushToken, unregisterPushToken } = useBeeperInbox();
await registerPushToken(fcmToken, { platform: "web" });
await unregisterPushToken(fcmToken);

The widget calls:

• POST /api/v1/projects/:projectId/widget/push/register
• POST /api/v1/projects/:projectId/widget/push/unregister

Security checklist

• Keep BEEPER_SERVER_KEY on your backend only. Never expose it in browser code.
• Use publishableKey only for widget initialization and widget-safe routes.
• Mint short-lived session tokens (ttlSeconds around 5-15 minutes).
• Refresh/re-mint session tokens from your backend when expired.
• Use onEvent to monitor session.refresh.error, api.error, and realtime.error.
• Rotate API keys periodically and revoke compromised keys immediately.

Package release checklist

pnpm -F beeper-inbox-react run clean
pnpm -F beeper-inbox-react run build
pnpm -F beeper-inbox-react run check-types

Then publish from packages/inbox-react using your normal npm release workflow.