Documentación
1. Genera un token en tu backend
Tu aplicación tiene una clave de firma. Tu backend ya sabe quién ha iniciado sesión, así que firma un token de corta duración que identifica a ese usuario. La clave nunca llega al navegador.
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. Coloca la campana en la página
<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>Es un elemento personalizado, así que funciona igual en React, Vue, Svelte, Rails o una página sin más. Vuelve a asignar el atributo token cuando lo renueves y el elemento se reconectará por su cuenta.
3. Publica desde tu 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"
}'El suscriptor se crea en la primera publicación, así que no hay ningún paso de sincronización de usuarios. Pasa un dedupeKey y, si tu gestor de tareas reintenta el envío, la campana no sonará dos veces.
SDK de servidor y React
¿Prefieres un cliente tipado a HTTP sin más? @notifybell/node publica, difunde y genera tokens de suscriptor, con reintentos ante 429 y 5xx. @notifybell/react muestra la campana como componente y renueva su token antes de que caduque. Ambos tienen licencia MIT y están en 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} />Darle estilo
El elemento se renderiza dentro de un shadow root, así que tu CSS no puede cambiarle el estilo por accidente ni sus estilos pueden filtrarse a tu página. Hay tres partes expuestas a propósito:
notify-bell::part(bell) { color: #64748b; }
notify-bell::part(badge) { background: #2563eb; }
notify-bell::part(panel) { border-radius: 4px; }Idioma, tema y eventos
Atributos: app-id, token, api-url, lang. La propiedad strings traduce cada palabra (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required…) y strings.categories nombra las categorías. Eventos: notify-bell:click y notify-bell:action se pueden cancelar; llama a preventDefault() para navegar dentro de la aplicación en lugar de abrir una pestaña; notify-bell:token-expired pide un token nuevo. El tema viene del panel; tus propiedades CSS en el elemento (--nb-accent, --nb-badge, --nb-radius) y ::part(bell | badge | panel | toast) siguen mandando.
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
Añade un endpoint por aplicación en la página Webhooks y NotifyBell le enviará eventos por POST: notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Cada petición lleva NotifyBell-Signature (t=marca de tiempo,v1=HMAC-SHA256 de "marca.cuerpo" con el secreto del endpoint); rechaza lo que no se verifique o tenga más de cinco minutos. Una respuesta que no sea 2xx se reintenta tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas, y después se marca como fallida y se guarda para reintentar a mano. Entrega al menos una vez: deduplica por el id del payload.
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)
}Referencia de la API
Los endpoints de backend requieren una clave de API (Authorization: Bearer nb_…). Los de la bandeja requieren un token de Suscriptor, como cabecera bearer o ?token=.
POST/api/v1/apps/{appId}/notifications
Publica para un suscriptor (subscriberId) o hasta 100 (subscriberIds). Opcional: body, category, actionUrl, iconUrl, data (objeto JSON de hasta 4 KB), priority, dedupeKey, actions (hasta dos botones {label, url}), expiresAt (ISO 8601, dentro de un año), template con variables, sendAt (entregar más tarde, dentro de 90 días). batch: {key, windowSeconds (60–86400), title con {{ count }}} agrupa una ráfaga en una notificación por suscriptor; no con sendAt. tenant: el id de tu espacio de trabajo; una campana cuyo token lleva tnt muestra las notificaciones de ese tenant y las que no tienen.
Clave de API
PATCH · DELETE/api/v1/apps/{appId}/notifications/{id}
PATCH reescribe una notificación enviada (title, body, actionUrl, iconUrl, data, actions; null borra) sin un segundo aviso. DELETE la retira de la bandeja. Las campanas abiertas se actualizan al momento.
Clave de API
DELETE/api/v1/apps/{appId}/notifications?dedupeKey=…
Retira todas las copias enviadas con esa clave de deduplicación: así se deshace una difusión. Los envíos programados y del panel usan scheduled:<id>.
Clave de API
POST/api/v1/apps/{appId}/broadcasts
Publica para todos los suscriptores de la aplicación o, con topic, para quienes siguen ese tema. Mismos campos opcionales que una publicación, incluidos template y sendAt. Con un dedupeKey, un reintento no notifica dos veces.
Clave de API
GET · DELETE/api/v1/apps/{appId}/scheduled[/{id}]
GET lista los envíos programados con su estado y cuántos se entregaron. DELETE /scheduled/{id} cancela uno que aún no ha salido.
Clave de API
GET/api/v1/apps/{appId}/templates
Las plantillas editadas en el panel. Publica una con template: "key" y variables: { … }; una variable que falte devuelve un 400 que la nombra.
Clave de API
GET/api/v1/apps/{appId}/subscribers
Los suscriptores de la app, los activos más recientes primero: limit (1–100), cursor. Se crean al publicarles.
Clave de API
GET · PUT/api/v1/apps/{appId}/subscribers/{externalId}/topics
Lee o sustituye los temas que sigue un suscriptor ({topics: [...]}, hasta 100). GET /topics lista cada tema con su número de seguidores.
Clave de API
GET · PATCH · DELETE/api/v1/apps/{appId}/subscribers/{externalId}
Consulta, actualiza (email, name; null borra) o elimina un suscriptor con todas sus notificaciones.
Clave de API
GET/api/v1/apps/{appId}/me/feed
Una página de la bandeja: limit (1–100), cursor, unreadOnly=true, archived=true, snoozed=true, category=a,b (solo esas categorías). Las notificaciones caducadas no aparecen. Devuelve los contadores de no leídas y no vistas.
Token de Suscriptor
GET/api/v1/apps/{appId}/me/stream
Server-Sent Events: ready, notification, read, unread, read-all, seen, archive, archive-read, update, retract, snooze.
Token de Suscriptor
POST/api/v1/apps/{appId}/me/read
Marca una como leída ({notificationId}), todas como leídas ({all: true}) o una como no leída ({notificationId, read: false}).
Token de Suscriptor
POST/api/v1/apps/{appId}/me/click
El usuario actuó sobre una notificación ({notificationId}, action opcional: 0 o 1 para un botón). También la marca como leída; cuenta como clic en las analíticas.
Token de Suscriptor
POST/api/v1/apps/{appId}/me/seen
Marca todo como visto ({all: true}); llámalo al abrir la campana.
Token de Suscriptor
POST/api/v1/apps/{appId}/me/archive
Archiva una ({notificationId}) o restáurala ({notificationId, archived: false}). O todas las leídas a la vez: {allRead: true, categories?}.
Token de Suscriptor
POST/api/v1/apps/{appId}/me/snooze
Posponer una notificación hasta un momento ({notificationId, until}: ISO 8601, como máximo 30 días). Sale del feed y de los contadores al instante y vuelve sin leer. until: null lo termina antes.
Token de Suscriptor
POST/api/v1/apps/{appId}/me/delete
Eliminar para siempre una notificación propia ({notificationId}). Archivar la conserva; esto no.
Token de Suscriptor
GET · PATCH/api/v1/apps/{appId}/me/preferences
Lee y ajusta las preferencias por categoría ({category, enabled}). Las obligatorias aparecen con required: true y no se pueden desactivar.
Token de Suscriptor
GET/api/v1/apps/{appId}/me/config
El tema y las etiquetas de categoría definidos en el panel. El embed los lee al cargar, así que un cambio no requiere desplegar.
Token de Suscriptor
Límites, con franqueza
- La difusión en tiempo real pasa por Redis. Cada instancia retransmite las nuevas notificaciones por un mismo canal de Redis, así que una campana conectada en cualquier sitio recibe una publicación procesada en cualquier otro. Si Redis no está disponible un momento, cada instancia sigue enviando a sus propias conexiones, y nunca se pierde nada, porque la bandeja se almacena en lugar de reproducirse.
- No hay email, SMS ni notificaciones push. A propósito. Si necesitas enrutado multicanal, este no es el producto que buscas.
- Cada stream se mantiene abierto quince minutos y luego se cierra, y el navegador se reconecta con el token que tiene el elemento. Los tokens de Suscriptor también duran quince minutos por defecto, así que vuelve a establecer el atributo token antes de que caduque; con un token caducado, la campana deja de actualizarse hasta que lo hagas. El elemento emite un evento notify-bell:token-expired cuando se rechaza su token, para que tu página pueda obtener uno nuevo en ese momento.
- Los tokens duran como máximo 24 horas. Se rechaza cualquier token de Suscriptor cuya caducidad esté a más de un día, lo haya emitido quien lo haya emitido, de modo que un token firmado con una clave que luego rotas no puede sobrevivirla mucho tiempo.
- Las solicitudes tienen límite de frecuencia. Publicar admite 1.200 solicitudes por minuto por clave de API; cada Suscriptor tiene 120 solicitudes de bandeja por minuto y hasta 5 streams abiertos. Por encima, la API responde 429 con una cabecera Retry-After.