App Notifications

Deliver in-app alerts to web and mobile clients using server-side publishes and client-side SDKs.

In-app notifications deliver real-time alerts to users while they are active in your application. The server publishes notification messages to user-specific topics, and client-side code displays them as toasts, badges, or notification panels.

Architecture

Each user subscribes to their own notification topic on login. Your server publishes notification payloads to that topic whenever an event occurs.

Notification Delivery

Your Server

publish

notify/{user_id}

User's Browser

User's Mobile

Because MQTT supports multiple subscribers on the same topic, notifications reach every device where the user is logged in simultaneously.

Topic Design

Topic	Purpose
`notify/{user_id}`	Personal notifications for a specific user
`notify/broadcast`	Organization-wide announcements
`notify/{user_id}/{category}`	Filtered notifications (e.g., `notify/alice/billing`)

Users subscribe to their personal topic on login. For category filtering, subscribe to notify/{user_id}/# and filter client-side, or subscribe only to specific categories.

How It Works

User logs in - the client connects to CloudSignal and subscribes to notify/{user_id}
Event occurs on your server (new message, payment received, threshold alert)
Server publishes a JSON notification payload to the user's topic via the CloudSignal REST API or an MQTT client
Client receives the message and renders it in the UI

Implementation with @cloudsignal/notifications

The notifications SDK provides React components for common notification patterns.

Add the Provider

import {
  CloudSignalProvider,
  NotificationProvider,
  NotificationToast
} from '@cloudsignal/notifications'

function App({ userId }) {
  return (
    <CloudSignalProvider
      host="wss://connect.cloudsignal.app:18885/"
      token="your-token"
    >
      <NotificationProvider userId={userId}>
        <NotificationToast position="top-right" />
        <YourApp />
      </NotificationProvider>
    </CloudSignalProvider>
  )
}

Display Notifications

import { useNotifications } from '@cloudsignal/notifications'

function NotificationBell() {
  const { notifications, unreadCount, markAsRead } = useNotifications()

  return (
    <div>
      <button>
        Notifications ({unreadCount})
      </button>
      <ul>
        {notifications.map((n) => (
          <li key={n.id} onClick={() => markAsRead(n.id)}>
            <strong>{n.title}</strong>
            <p>{n.body}</p>
          </li>
        ))}
      </ul>
    </div>
  )
}

Server-Side Publishing

Node.js

const response = await fetch('https://api.cloudsignal.com/v2/publish', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    topic: `notify/${userId}`,
    payload: JSON.stringify({
      id: crypto.randomUUID(),
      title: 'New message',
      body: 'You have a new message from Bob',
      category: 'messages',
      timestamp: Date.now(),
      action: { url: '/messages/123' }
    }),
    qos: 1
  })
})

Python

import requests
import json
import uuid
from datetime import datetime

requests.post(
    "https://api.cloudsignal.com/v2/publish",
    headers={
        "Authorization": "Bearer sk_your_secret_key",
        "Content-Type": "application/json"
    },
    json={
        "topic": f"notify/{user_id}",
        "payload": json.dumps({
            "id": str(uuid.uuid4()),
            "title": "Payment received",
            "body": f"Payment of ${amount:.2f} has been processed",
            "category": "billing",
            "timestamp": datetime.now().isoformat(),
            "action": {"url": "/billing/history"}
        }),
        "qos": 1
    }
)

Use QoS 1 for notifications to ensure delivery. If the user is temporarily disconnected with a persistent session, the notification will be delivered when they reconnect.

Notification Payload Structure

A consistent payload schema makes client rendering predictable:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Short headline",
  "body": "Longer description text",
  "category": "messages",
  "timestamp": "2026-03-22T10:30:00Z",
  "action": {
    "url": "/messages/123"
  },
  "priority": "normal"
}

Next Steps

Notifications SDK reference - full API for the React notification components
Push Notifications - extend to native push when the app is in the background
Offline Caching - ensure notifications are delivered even after disconnection

On this page