FAQ

Answers to common questions about NotificationStream.

Is this push notifications?

No. NotificationStream is an in-app notification center: a bell, drawer and inbox inside your web or mobile app, like the ones in social and productivity apps. It doesn't send OS push notifications, emails or SMS. Many teams use it next to push or email: the inbox is where notifications stay available after the push is dismissed.

Polling or realtime?

Both are opt-in; without either, the SDKs fetch when users open or return to your app. Realtime (useRealtime() / client.realtime(), Growth plan and up) keeps a WebSocket open that says when the user's feed changed, so new notifications appear within seconds and each user uses one request per connection plus one per change. Polling (usePolling(interval) / client.poll(interval)) checks on a timer; each poll is one small request that usually returns an empty 304. Polling pauses while realtime is connected, so turning on both makes polling the fallback. Either way the SDKs only poll or stay connected while your app is visible, and one browser tab does it for all the others. See Polling, realtime and performance.

How fast does a notification show up?

With realtime, within seconds (broadcasts to many connected users are spread over up to 30 seconds). With polling, within the poll interval for users audiences, and up to about 30 seconds more for broadcasts (all, tags, segments), which are cached per project. Users also get a refetch when they come back to the tab or app. Details in Polling, realtime and performance.

Do users need to exist before I send to them?

No. Sending to a user id creates a placeholder project user, and the user sees the notification on their first visit. Broadcasts (all, tags, segments) also reach users created after you sent them.

Can I send to a million users?

Yes. Use all, or tags or a segment on the Growth plan and up: one notification reaches every matching user. Sending never counts against your plan's requests, however many users it reaches; what counts is each user's SDK fetching their feed. users audiences are limited to 1,000 user ids per notification.

Can I edit a notification after sending it?

Published notifications are immutable. You can cancel one to remove it from every feed (it stays in your history), then send a corrected one. Drafts and scheduled notifications can be edited. See Scheduling and expiry.

What counts as an API request?

Every call the SDKs make: fetching the feed (including 304 replies), opening a realtime connection (its messages don't count), actions such as marking read, and profile syncs. Refused requests (401, 402, 403, 429) don't count, and neither do server API calls. With polling every minute, a typical user makes about 400 a month. See Billing and limits.

What happens if my subscription lapses?

While a failed payment is being retried (past_due), everything keeps working. Once the subscription is canceled, unpaid or paused, every API write (sending, editing, project users, segments) and every SDK request returns 402 payment_required until you renew. The SDKs then show an empty feed and stop polling and realtime. You can still read your data through the API.

Is the publishable key a secret?

No. It's meant to be embedded in your frontend. What protects your users is user tokens signed by your backend and, for browsers, allowed origins.

Can users see each other's notifications?

No. Every request carries a user token for one user id, signed with a key only your backend holds. Each user only sees notifications whose audience includes them.

Does it work with server-side rendering?

Yes. The JavaScript SDK doesn't touch the DOM at import time, and the React SDK is marked "use client" and fetches nothing on the server. For server-rendered inboxes or digest emails, use GET /v1/project-users/{userId}/feed.

Can I build my own UI?

Yes. Use the headless client (createNotificationClient) or the React hooks (useNotifications), or call the REST API directly. The theme, label and Markdown helpers of the JavaScript SDK give you the same building blocks the bundled UIs use.

How do I delete a user's data?

DELETE /v1/project-users/{userId} deletes the project user and all their notification state.

Can I run it myself?

Not yet. Self-hosting is coming soon; until then, use the hosted service.