Документация
1. Выпустите токен на своём бэкенде
У вашего приложения есть ключ для подписи. Бэкенд и так знает, кто вошёл в систему, поэтому он подписывает недолговечный токен с именем этого пользователя. Сам ключ никогда не попадает в браузер.
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. Поместите колокольчик на страницу
<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>Это пользовательский элемент, поэтому он одинаково работает в React, Vue, Svelte, Rails или на обычной странице. Просто задайте атрибут token заново при обновлении — и элемент переподключится сам.
3. Отправляйте уведомления с бэкенда
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"
}'Подписчик создаётся при первой отправке, поэтому отдельный шаг синхронизации пользователей не нужен. Передайте dedupeKey — и повторная попытка из вашего обработчика задач не заставит колокольчик прозвенеть дважды.
SDK для сервера и React
Нужен типизированный клиент вместо голого HTTP? @notifybell/node публикует уведомления, делает рассылки и выпускает токены подписчиков, повторяя запросы при 429 и 5xx. @notifybell/react выводит колокольчик как компонент и обновляет его токен до истечения срока. Оба пакета под лицензией MIT и доступны в 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} />Оформление
Элемент отрисовывается внутри shadow root, поэтому ваш CSS не может случайно изменить его вид, а его собственные стили не протекают на вашу страницу. Три части открыты намеренно:
notify-bell::part(bell) { color: #64748b; }
notify-bell::part(badge) { background: #2563eb; }
notify-bell::part(panel) { border-radius: 4px; }Язык, оформление и события
Атрибуты: app-id, token, api-url, lang. Свойство strings переводит каждое слово (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required…), а strings.categories задаёт названия категорий. События: notify-bell:click и notify-bell:action можно отменить — вызовите preventDefault(), чтобы перейти внутри приложения вместо новой вкладки; notify-bell:token-expired просит новый токен. Тема берётся из панели; ваши CSS-свойства на элементе (--nb-accent, --nb-badge, --nb-radius) и ::part(bell | badge | panel | toast) важнее.
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; }Вебхуки
Добавьте эндпоинт для каждого приложения на странице «Вебхуки», и NotifyBell будет отправлять на него события POST-запросами: notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Каждый запрос содержит NotifyBell-Signature (t=метка времени,v1=HMAC-SHA256 от "метка.тело" с секретом эндпоинта); отклоняйте всё, что не проходит проверку или старше пяти минут. Ответ не из 2xx повторяется через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов, затем помечается как неудачный и сохраняется для ручного повтора. Доставка как минимум один раз: дедуплицируйте по id в теле.
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)
}Справочник API
Эндпоинты бэкенда принимают API-ключ (Authorization: Bearer nb_…). Эндпоинты ленты принимают токен Подписчика — в заголовке bearer или в ?token=.
POST/api/v1/apps/{appId}/notifications
Публикует одному подписчику (subscriberId) или до 100 (subscriberIds). Необязательно: body, category, actionUrl, iconUrl, data (JSON-объект до 4 КБ), priority, dedupeKey, actions (до двух кнопок {label, url}), expiresAt (ISO 8601, не дальше года), template с variables, sendAt (отложенная доставка, до 90 дней). batch: {key, windowSeconds (60–86400), title с {{ count }}} объединяет серию в одно уведомление на подписчика; не вместе с sendAt. tenant: идентификатор вашего рабочего пространства; колокольчик, чей токен содержит tnt, показывает уведомления этого tenant и без него.
API-ключ
PATCH · DELETE/api/v1/apps/{appId}/notifications/{id}
PATCH изменяет уже отправленное уведомление (title, body, actionUrl, iconUrl, data, actions; null очищает) без повторного сигнала. DELETE отзывает его из ящика. Открытые колокольчики обновляются сразу.
API-ключ
DELETE/api/v1/apps/{appId}/notifications?dedupeKey=…
Отзывает все копии, отправленные с этим ключом дедупликации, — так отменяется рассылка. Запланированные отправки и отправки из панели используют scheduled:<id>.
API-ключ
POST/api/v1/apps/{appId}/broadcasts
Публикует всем подписчикам приложения или, с topic, всем, кто следит за темой. Те же необязательные поля, что и при публикации, включая template и sendAt. dedupeKey гарантирует, что повторный запрос никого не уведомит дважды.
API-ключ
GET · DELETE/api/v1/apps/{appId}/scheduled[/{id}]
GET возвращает запланированные отправки со статусом и числом доставок. DELETE /scheduled/{id} отменяет ещё не отправленную.
API-ключ
GET/api/v1/apps/{appId}/templates
Шаблоны, созданные в панели. Публикуйте с template: "key" и variables: { … }; при отсутствии переменной вернётся 400 с её именем.
API-ключ
GET/api/v1/apps/{appId}/subscribers
Подписчики приложения, сначала недавно активные: limit (1–100), cursor. Подписчик создаётся при первой публикации ему.
API-ключ
GET · PUT/api/v1/apps/{appId}/subscribers/{externalId}/topics
Читает или заменяет темы подписчика ({topics: [...]}, до 100). GET /topics возвращает все темы с числом подписчиков.
API-ключ
GET · PATCH · DELETE/api/v1/apps/{appId}/subscribers/{externalId}
Найти, изменить (email, name; null очищает) или удалить подписчика со всеми его уведомлениями.
API-ключ
GET/api/v1/apps/{appId}/me/feed
Страница ящика: limit (1–100), cursor, unreadOnly=true, archived=true, snoozed=true, category=a,b (только эти категории). Истёкшие уведомления не показываются. Возвращает счётчики непрочитанных и непросмотренных.
Токен Подписчика
GET/api/v1/apps/{appId}/me/stream
Server-Sent Events: ready, notification, read, unread, read-all, seen, archive, archive-read, update, retract, snooze.
Токен Подписчика
POST/api/v1/apps/{appId}/me/read
Отметить одно прочитанным ({notificationId}), все прочитанными ({all: true}) или одно непрочитанным ({notificationId, read: false}).
Токен Подписчика
POST/api/v1/apps/{appId}/me/click
Пользователь отреагировал на уведомление ({notificationId}, необязательно action: 0 или 1 для кнопки). Также отмечает прочитанным; учитывается в аналитике как клик.
Токен Подписчика
POST/api/v1/apps/{appId}/me/seen
Отметить всё просмотренным ({all: true}) — вызывайте при открытии колокольчика.
Токен Подписчика
POST/api/v1/apps/{appId}/me/archive
Архивировать одно ({notificationId}) или вернуть ({notificationId, archived: false}). Или все прочитанные сразу: {allRead: true, categories?}.
Токен Подписчика
POST/api/v1/apps/{appId}/me/snooze
Отложить уведомление до момента ({notificationId, until}: ISO 8601, не более 30 дней). Оно сразу исчезает из ленты и счётчиков и возвращается непрочитанным. until: null завершает откладывание раньше.
Токен Подписчика
POST/api/v1/apps/{appId}/me/delete
Окончательно удалить своё уведомление ({notificationId}). Архив его сохраняет, удаление — нет.
Токен Подписчика
GET · PATCH/api/v1/apps/{appId}/me/preferences
Чтение и изменение настроек по категориям ({category, enabled}). Обязательные категории помечены required: true, отключить их нельзя.
Токен Подписчика
GET/api/v1/apps/{appId}/me/config
Тема и подписи категорий из панели. Встраиваемый компонент читает их при загрузке, поэтому изменения не требуют выкладки.
Токен Подписчика
Честные ограничения
- Рассылка в реальном времени идёт через Redis. Каждый экземпляр передаёт новые уведомления через общий канал Redis, поэтому колокольчик, подключённый к любому экземпляру, получает публикацию, обработанную любым другим. Если Redis ненадолго недоступен, каждый экземпляр продолжает обслуживать свои подключения, и ничего не теряется, потому что лента хранится, а не воспроизводится.
- Нет ни email, ни SMS, ни push-уведомлений. И это осознанно. Если вам нужна маршрутизация по нескольким каналам, это не тот продукт.
- Поток держится пятнадцать минут, после чего закрывается, и браузер переподключается с токеном, который сейчас у элемента. Токены Подписчиков по умолчанию тоже действуют пятнадцать минут, поэтому задайте атрибут token заново до их истечения — с просроченным токеном колокольчик перестаёт обновляться, пока вы этого не сделаете. Элемент отправляет событие notify-bell:token-expired, когда его токен отклонён, чтобы ваша страница могла в этот момент получить новый.
- Токен действует не дольше 24 часов. Токен Подписчика со сроком действия больше суток отклоняется, кто бы его ни выпустил, поэтому токен, подписанный ключом, который вы потом смените, не переживёт его надолго.
- Запросы ограничены по частоте. Публикация — до 1 200 запросов в минуту на API-ключ; у каждого Подписчика — 120 запросов к ленте в минуту и до 5 открытых потоков. Сверх этого API отвечает 429 с заголовком Retry-After.