Introduction

What NotificationStream is, what it is for, and how a notification travels from your backend to your users.

NotificationStream gives your product the in-app notifications users already know from social and productivity apps: a bell with an unread badge, a drawer that opens from it, and a full-page inbox. You send notifications from your backend or the dashboard; the SDKs render them in your web or mobile app.

Why use it

How it works

  Your backend                 NotificationStream API                Your app (SDK)
  ────────────                 ──────────────────────                ──────────────
  POST /v1/notifications  ───▶ stores the notification with its
  (secret key sk_…)            audience, schedule and expiry

  GET /api/notifications/token ──────────────────────────────▶ user token (JWT, sub = user id)
  (signs with your signing key)

                                                        ◀───  GET /v1/client/feed
                               verifies publishable key,      (X-Publishable-Key: pk_…,
                               user token and origin,          Authorization: Bearer <token>)
                               matches broadcasts against      on load, on return and
                               the user (tags, segments),      on a realtime signal or poll
                               localizes and personalizes,
                               returns items + counts (or 304) ───▶ bell, drawer, inbox

                                                        ◀───  POST /v1/client/actions
                               records read / archive / click      (read, archive, click,
                               and returns the new counts           mark all as read/seen)

1. Your backend sends a notification with a secret key (sk_…), either through the Node SDK or the REST API. It picks an audience, localized contents, and optionally a schedule, expiry, category, action URL, image and custom data.
2. Your backend signs a user token. A short-lived JWT, signed with one of your project's signing keys, that names the signed-in user (see Identity verification). The SDK sends it with every request, next to your project's publishable key (pk_…).
3. The SDK fetches the feed when it starts and when the user returns to your app, plus when the feed changes if you turn on realtime (Growth plan and up), or on a timer if you turn on polling. Each fetch returns the user's notifications, already localized and personalized, plus unreadCount, unseenCount and the project's remote configuration (theme, default locale). When nothing changed, the browser gets an empty 304 Not Modified, which still counts as a request.
4. Users interact. Opening the drawer clears the badge (seen_all), clicking an item marks it read and records the click, and users can archive or mark everything read. You can see read and click counts per notification in the dashboard or via GET /v1/notifications/{id}.

What's in the box

Next steps