Documentation
1. Générez un jeton depuis votre backend
Votre application dispose d'une clé de signature. Votre backend sait déjà qui est connecté : il signe donc un jeton de courte durée au nom de cet utilisateur. La clé n'arrive jamais jusqu'au navigateur.
import { createHmac } from 'node:crypto'
function mintToken(appId, userId, signingKey, ttlSeconds = 900) {
const payload = {
aid: appId,
sub: userId, // your own user id
exp: Math.floor(Date.now() / 1000) + ttlSeconds,
// tnt: workspaceId, // optional: one tenant's bell
}
const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url')
const signature = createHmac('sha256', signingKey).update(encoded).digest('base64url')
return `${encoded}.${signature}`
}2. Placez la cloche sur la page
<script src="https://notifybell.altixcode.com/embed/notify-bell.js" defer></script>
<notify-bell app-id="app_…" token="…" api-url="https://notifybell.altixcode.com"></notify-bell>Il s'agit d'un élément personnalisé : il fonctionne donc de la même façon avec React, Vue, Svelte, Rails ou une simple page HTML. Redéfinissez l'attribut token lorsque vous le renouvelez et l'élément se reconnecte de lui-même.
3. Publiez depuis votre backend
curl -X POST https://notifybell.altixcode.com/api/v1/apps/APP_ID/notifications \
-H "Authorization: Bearer nb_…" \
-H "Content-Type: application/json" \
-d '{
"subscriberId": "usr_99812",
"title": "Deployment completed",
"body": "Your production build v1.4.2 was deployed.",
"category": "system",
"actionUrl": "https://app.example.com/deployments/123",
"dedupeKey": "deploy-123"
}'L'abonné est créé dès la première publication : aucune étape de synchronisation des utilisateurs n'est nécessaire. Transmettez une dedupeKey et une nouvelle tentative de votre gestionnaire de tâches ne fera pas sonner la cloche deux fois.
SDK serveur et React
Vous préférez un client typé à du HTTP brut ? @notifybell/node publie, diffuse et génère les jetons d’abonné, avec nouvelles tentatives sur 429 et 5xx. @notifybell/react affiche la cloche comme composant et renouvelle son jeton avant son expiration. Les deux sont sous licence MIT et disponibles sur npm.
npm install @notifybell/node @notifybell/react
// server
import { NotifyBell, mintSubscriberToken } from '@notifybell/node'
const app = new NotifyBell({ apiKey: process.env.NOTIFYBELL_API_KEY }).app('app_123')
await app.publish({ subscriberId: user.id, title: 'Your export is ready' })
const token = mintSubscriberToken({ appId: 'app_123', subscriberId: user.id, signingKey })
// React
import { NotifyBell } from '@notifybell/react'
<NotifyBell appId="app_123" token={token} getToken={fetchFreshToken} />Personnaliser le style
L'élément s'affiche dans un shadow root : votre CSS ne risque donc pas d'en modifier le style par accident, et ses styles ne peuvent pas se propager à votre page. Trois parties sont exposées délibérément :
notify-bell::part(bell) { color: #64748b; }
notify-bell::part(badge) { background: #2563eb; }
notify-bell::part(panel) { border-radius: 4px; }Langue, thème et événements
Attributs : app-id, token, api-url, lang. La propriété strings traduit chaque mot (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required…) et strings.categories nomme les catégories. Événements : notify-bell:click et notify-bell:action sont annulables — appelez preventDefault() pour naviguer dans l’application au lieu d’ouvrir un onglet ; notify-bell:token-expired demande un nouveau jeton. Le thème vient du tableau de bord ; vos propriétés CSS sur l’élément (--nb-accent, --nb-badge, --nb-radius) et ::part(bell | badge | panel | toast) restent prioritaires.
const bell = document.querySelector('notify-bell')
bell.strings = {
title: 'Benachrichtigungen',
markAll: 'Alle gelesen',
categories: { billing: 'Rechnungen' },
}
bell.addEventListener('notify-bell:click', (event) => {
event.preventDefault() // route in-app instead of opening a tab
router.push(event.detail.data.path)
})
bell.addEventListener('notify-bell:token-expired', async () => {
bell.setAttribute('token', await fetchFreshToken())
})
/* CSS */
notify-bell { --nb-accent: #0f766e; --nb-badge: #b91c1c; --nb-radius: 8px; }Webhooks
Ajoutez un endpoint par application sur la page Webhooks et NotifyBell y envoie les événements en POST : notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Chaque requête porte NotifyBell-Signature (t=horodatage,v1=HMAC-SHA256 de "horodatage.corps" avec le secret de l’endpoint) ; rejetez tout ce qui ne se vérifie pas ou date de plus de cinq minutes. Une réponse hors 2xx est retentée après 1 minute, 5 minutes, 30 minutes, 2 heures et 12 heures, puis marquée en échec et conservée pour une relance manuelle. Livraison au moins une fois : dédupliquez sur l’id de la charge utile.
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: the request body exactly as received, before JSON parsing.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const age = Math.abs(Date.now() / 1000 - Number(parts.t))
if (!parts.t || !parts.v1 || age > 300) return false
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest()
const given = Buffer.from(parts.v1, 'hex')
return given.length === expected.length && timingSafeEqual(given, expected)
}Référence de l’API
Les endpoints backend attendent une clé d'API (Authorization: Bearer nb_…). Les endpoints de boîte de réception attendent un jeton d'Abonné, en en-tête bearer ou en ?token=.
POST/api/v1/apps/{appId}/notifications
Publie pour un abonné (subscriberId) ou jusqu’à 100 (subscriberIds). Facultatif : body, category, actionUrl, iconUrl, data (objet JSON de 4 Ko max.), priority, dedupeKey, actions (jusqu’à deux boutons {label, url}), expiresAt (ISO 8601, dans l’année), template avec variables, sendAt (envoi différé, sous 90 jours). batch : {key, windowSeconds (60–86400), title avec {{ count }}} regroupe une rafale en une notification par abonné ; pas avec sendAt. tenant : votre identifiant d’espace de travail ; une cloche dont le jeton porte tnt affiche les notifications de ce tenant et celles sans tenant.
Clé d'API
PATCH · DELETE/api/v1/apps/{appId}/notifications/{id}
PATCH réécrit une notification envoyée (title, body, actionUrl, iconUrl, data, actions ; null efface) sans nouvelle sonnerie. DELETE la retire de la boîte. Les cloches ouvertes se mettent à jour en direct.
Clé d'API
DELETE/api/v1/apps/{appId}/notifications?dedupeKey=…
Retire chaque copie envoyée avec cette clé de déduplication — c’est ainsi qu’on reprend une diffusion. Les envois programmés et du tableau de bord utilisent scheduled:<id>.
Clé d'API
POST/api/v1/apps/{appId}/broadcasts
Publie pour tous les abonnés de l’application, ou avec topic pour tous ceux qui suivent ce sujet. Mêmes champs facultatifs qu’une publication, dont template et sendAt. Un dedupeKey évite toute double notification en cas de nouvel essai.
Clé d'API
GET · DELETE/api/v1/apps/{appId}/scheduled[/{id}]
GET liste les envois programmés avec leur statut et le nombre de remises. DELETE /scheduled/{id} annule un envoi pas encore parti.
Clé d'API
GET/api/v1/apps/{appId}/templates
Les modèles édités dans le tableau de bord. Publiez-en un avec template: "key" et variables: { … } ; une variable manquante renvoie un 400 qui la nomme.
Clé d'API
GET/api/v1/apps/{appId}/subscribers
Les abonnés de l’application, les plus récemment actifs d’abord : limit (1–100), cursor. Un abonné est créé au premier envoi.
Clé d'API
GET · PUT/api/v1/apps/{appId}/subscribers/{externalId}/topics
Lit ou remplace les sujets suivis par un abonné ({topics: [...]}, jusqu’à 100). GET /topics liste chaque sujet avec son nombre d’abonnés.
Clé d'API
GET · PATCH · DELETE/api/v1/apps/{appId}/subscribers/{externalId}
Consulter, modifier (email, name ; null efface) ou effacer un abonné avec toutes ses notifications.
Clé d'API
GET/api/v1/apps/{appId}/me/feed
Une page de la boîte : limit (1–100), cursor, unreadOnly=true, archived=true, snoozed=true, category=a,b (seulement ces catégories). Les notifications expirées sont exclues. Renvoie les compteurs non lus et non vus.
Jeton d'Abonné
GET/api/v1/apps/{appId}/me/stream
Server-Sent Events : ready, notification, read, unread, read-all, seen, archive, archive-read, update, retract, snooze.
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/read
Marquer une notification lue ({notificationId}), toutes lues ({all: true}) ou une non lue ({notificationId, read: false}).
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/click
L’utilisateur a agi sur une notification ({notificationId}, action facultative : 0 ou 1 pour un bouton). La marque aussi comme lue ; compte comme un clic dans les statistiques.
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/seen
Tout marquer comme vu ({all: true}) — à appeler à l’ouverture de la cloche.
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/archive
Archiver une notification ({notificationId}) ou la restaurer ({notificationId, archived: false}). Ou toutes celles déjà lues d’un coup : {allRead: true, categories?}.
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/snooze
Mettre une notification en pause jusqu’à un instant ({notificationId, until} : ISO 8601, 30 jours au plus). Elle quitte le flux et les compteurs tout de suite et revient non lue. until: null y met fin plus tôt.
Jeton d'Abonné
POST/api/v1/apps/{appId}/me/delete
Supprimer définitivement une de ses propres notifications ({notificationId}). L’archivage la conserve, ceci non.
Jeton d'Abonné
GET · PATCH/api/v1/apps/{appId}/me/preferences
Lire et régler les choix par catégorie ({category, enabled}). Les catégories obligatoires portent required: true et ne peuvent pas être coupées.
Jeton d'Abonné
GET/api/v1/apps/{appId}/me/config
Le thème et les libellés de catégories définis dans le tableau de bord. L’embed les lit au chargement : aucun déploiement nécessaire.
Jeton d'Abonné
Les limites, en toute franchise
- La diffusion en temps réel passe par Redis. Chaque instance relaie les nouvelles notifications par un même canal Redis : une cloche connectée n'importe où reçoit une publication traitée n'importe où. Si Redis est brièvement injoignable, chaque instance continue de servir ses propres connexions, et rien n'est jamais perdu, car la boîte de réception est stockée et non rejouée.
- Il n'y a ni e-mail, ni SMS, ni notification push. C'est délibéré. Si vous avez besoin d'un routage multicanal, ce produit n'est pas fait pour vous.
- Un flux reste ouvert pendant quinze minutes, puis il est fermé et le navigateur se reconnecte avec le jeton que détient l'élément. Les jetons d'Abonné durent aussi quinze minutes par défaut : redéfinissez l'attribut token avant leur expiration, sinon la cloche cesse de se mettre à jour jusqu'à ce que vous le fassiez. L'élément émet un événement notify-bell:token-expired lorsque son jeton est refusé, afin que votre page puisse en récupérer un nouveau à ce moment-là.
- Les jetons vivent au plus 24 heures. Un jeton d'Abonné dont l'expiration est à plus d'un jour est refusé, quel que soit son émetteur : un jeton signé avec une clé que vous renouvelez ensuite ne peut pas lui survivre longtemps.
- Les requêtes sont limitées en débit. La publication autorise 1 200 requêtes par minute et par clé d'API ; chaque Abonné dispose de 120 requêtes de boîte de réception par minute et de 5 flux ouverts au maximum. Au-delà, l'API répond 429 avec un en-tête Retry-After.