Your first notification, in about ten minutes.

1. 01

   You send

   Your backend makes one API call: a notification type, who it is for, and the data behind it. You never send the words.

2. 02

   We render and deliver

   We look up your template, write the sentence in each recipient’s language, put it in their feed and push it to their devices.

3. 03

   Your users read

   Your app asks for that person’s feed and gets back both the finished text and the raw data, so you can draw it however you like.

The reason you send data rather than words is that a push notification is drawn by the phone while your app is closed. No code of yours runs at that moment, so the finished sentence has to already exist. Keeping the words with us is what lets the same call fill the feed, the phone and the browser.

1. 1

   Describe the notification

   In the console, under Notification types, create a type. Give it a key you will use in code, like invoice.paid, and list the data it carries.

   The data an invoice.paid notification carries

   {
     "invoice_number": "string",
     "amount":         "string",
     "customer_name":  "string"
   }

   We check every send against this. A typo in your backend is rejected at the API with a clear message, instead of arriving as a notification with a blank in the middle of it.

2. 2

   Write the words

   Still on the type, write a template. One row per language, with a live preview beside it. Anything in curly braces is filled in from the data you send.

   English

   Title  Invoice {invoice_number} is paid
   Body   {customer_name} paid {amount}. Nothing else to do.

   Add the other eighteen languages whenever you like. Until then everyone gets your default one, and the console shows you exactly which are missing.

3. 3

   Send one

   From your backend, with the API key from Settings. recipients holds your user ids — the ones your own database already uses.

   POST https://api.bzzt.now/v1/notifications

   curl https://api.bzzt.now/v1/notifications \
     -H "Authorization: Bearer $BZZT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "invoice.paid",
       "recipients": ["user_8812"],
       "payload": {
         "invoice_number": "INV-2026-0041",
         "amount": "€2,400",
         "customer_name": "Globex"
       }
     }'

   You get 202 Accepted straight away. That is not us being vague: the notification does not exist yet, and saying it does would be a lie you could catch by reading the feed a millisecond later. It lands within a second or two.

   Nothing built yet? Use Send a notification in the console and send the same thing by hand first. Same path, same result — see the console.

4. 4

   Show it in your app

   Your backend mints a short-lived token for the signed-in user, your frontend fetches it, and then talks to us directly. We never see your passwords or your sessions.

   Your frontend, with that token

   const res = await fetch("https://api.bzzt.now/v1/me/notifications", {
     headers: { Authorization: `Bearer ${bzztToken}` },
   });
   
   const { items } = await res.json();
   
   items[0];
   // {
   //   id: "nt_7c1e…",
   //   typeKey: "invoice.paid",
   //   content: { title: "Invoice INV-2026-0041 is paid", body: "Globex paid €2,400…" },
   //   data:    { invoice_number: "INV-2026-0041", amount: "€2,400", … },
   //   createdAt: "2026-10-20T09:12:04.182Z",
   //   seenAt: null, readAt: null, archivedAt: null
   // }

   Every item gives you both. Use content and you are done; use data if you would rather build the sentence yourself in the client.

   In JavaScript or TypeScript, the SDK does the fetching, the live connection, reconnecting and the unread counts for you:

   npm install @bzzt/client

   import { NotificationClient } from "@bzzt/client";
   
   const client = new NotificationClient({
     baseUrl: "https://api.bzzt.now",
     // Called on every connect, not once: tokens expire, sockets outlive them.
     getToken: () => fetchShortLivedToken(),
   });
   
   client.subscribe(({ items, counts }) => render(items, counts.unread));
   await client.start();

   It also gives you markRead, archive, fetchNextPage and device registration, applied optimistically so the interface responds immediately. The REST endpoints below are exactly what it calls, so you can start with one and move to the other without changing anything on your server.

We do not store your users. No names, no email addresses, no passwords. We know a person only by an id that you choose — almost always the id already in your own database.

That id shows up in exactly two places, and they have to agree.

Same string, same person, and the feed fills up. We compare them character for character and do nothing clever: we have no other way of knowing that two ids are the same human.

Check it in thirty seconds

Before wiring anything else: send one notification to yourself, then load your own feed. If the notification is there, the two sides agree and they will keep agreeing. If the feed is empty, print both values side by side — the problem is always visible the moment you do.

Minting the token

A few lines on an endpoint of your own. Sign it with the key you gave us and keep it short-lived.

jwt.sign(
  {
    sub: currentUser.id,         // ← the same id you send as a recipient
    iss: "https://your-app.com", // the issuer we hold for you
  },
  yourPrivateKey,
  { algorithm: "RS256", expiresIn: "1h" },
);

To reach a whole company, pass every id in one call. We expand it in the background in batches, so the call returns just as fast for ten thousand people as for one, and a problem delivering to one person never holds up anybody else.

Seen, read and archived are three separate things rather than one status, because they really are separate: somebody can scroll past a notification without opening it, or dismiss one they never read. Each is a timestamp, or null.

const socket = new WebSocket(
  `wss://api.bzzt.now/v1/me/stream?token=${bzztToken}`
);

socket.onmessage = (event) => {
  const hint = JSON.parse(event.data);
  // { id, typeKey, unreadCount, cursor }
  setBadge(hint.unreadCount);
};

The message is a hint, not the notification itself. Treat it as a nudge to update your badge and, if the list is on screen, to fetch what is new. Reading a notification on a phone clears the badge on an open laptop the same way.

Push works in two halves: getting a device token from the phone or browser, and telling us about it.

Getting a device token

This part happens inside your app, not against our API. Both Apple and Google hand out a token that identifies one installation on one device, and the usual way to ask for it on all three platforms is Firebase Cloud Messaging:

Telling us about it

Once you have a token, register it when somebody signs in and remove it when they sign out.

await fetch("https://api.bzzt.now/v1/me/devices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${bzztToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: deviceToken,   // the one Firebase gave you
    platform: "ios",      // "ios" | "android" | "web"
    locale: "pl",         // optional
  }),
});

Call it on every app start. Registering the same device twice is harmless, and it is how we know the device is still alive. Someone with a phone, a tablet and two browsers gets the notification on all four. The SDK exports registerDevice and removeDevice if you would rather not write the fetch.

Everything here is scoped to your workspace. Your colleagues sign in with their work email and see only your data — there is no shared login and no password to pass around.