notifications
websocket

GET /api/v1/notifications/websocket-docs

WebSocket Events

The notification system uses WebSocket (Socket.IO) for real-time bidirectional communication.

Connection

Endpoint: ws://localhost:3000 (or wss:// in production)

Authentication:

  1. Connect to WebSocket server
  2. Emit authenticate event with JWT token
  3. Server responds with authenticated or unauthorized
const socket = io('ws://localhost:3000');
socket.emit('authenticate', { token: 'your-jwt-token' });

socket.on('authenticated', () => {
  console.log('Connected and authenticated');
});

socket.on('unauthorized', (error) => {
  console.error('Authentication failed:', error);
});

Client Events (Client → Server)

  • authenticate: Authenticate WebSocket connection

    • Payload: { token: string }
    • Response: authenticated or unauthorized event
  • notification:read: Mark notification as read (deprecated, use REST API)

    • Payload: { notificationId: string }
  • notification:read-all: Mark all notifications as read (deprecated, use REST API)

    • Payload: none

Server Events (Server → Client)

  • notification:new: New notification created

    • Payload: Notification object with all fields
    • Emitted to all user connections when notification is created
  • notification:read: Notification marked as read

    • Payload: { notificationId: string, readAt: string }
    • Emitted to all user connections when notification is marked as read
  • notification:unread: Notification marked as unread

    • Payload: { notificationId: string }
    • Emitted to all user connections when notification is marked as unread
  • notification:count: Unread notification count update

    • Payload: number (unread count)
    • Emitted when count changes (new notification, mark as read, mark all as read/unread)
  • notification:all-read: All notifications marked as read

    • Payload: { timestamp: string }
    • Emitted when user marks all notifications as read
  • notification:all-unread: All read notifications marked as unread

    • Payload: { timestamp: string, unreadCount: number }
    • Emitted when user marks read notifications as unread

Bot Events (Server ↔ Bot)

  • bot:deliver (Server → Bot): Deliver notification via Discord

    • Payload: BotDeliveryPayload with notification data and template
    • Bot should send Discord message and report status
  • bot:delivery-status (Bot → Server): Report delivery status

    • Payload: { notificationId: string, success: boolean, discordMessageId?: string, error?: string }
    • Bot reports success or failure of Discord message delivery

Example Usage

// Listen for new notifications
socket.on('notification:new', (notification) => {
  console.log('New notification:', notification);
  // Update UI with new notification
});

// Listen for count updates
socket.on('notification:count', (count) => {
  console.log('Unread count:', count);
  // Update badge count in UI
});

// Listen for read status updates
socket.on('notification:read', ({ notificationId, readAt }) => {
  console.log('Notification marked as read:', notificationId);
  // Update notification UI to show as read
});

// Listen for unread status updates
socket.on('notification:unread', ({ notificationId }) => {
  console.log('Notification marked as unread:', notificationId);
  // Update notification UI to show as unread
});

// Listen for mark all as read
socket.on('notification:all-read', ({ timestamp }) => {
  console.log('All notifications marked as read at:', timestamp);
  // Update UI to show all as read
});

// Listen for mark all as unread
socket.on('notification:all-unread', ({ timestamp, unreadCount }) => {
  console.log('All read notifications marked as unread at:', timestamp, unreadCount);
  // Update UI to show affected notifications as unread
});

Reconnection

The client should implement automatic reconnection with exponential backoff:

let reconnectAttempts = 0;
const maxReconnectDelay = 30000; // 30 seconds

socket.on('disconnect', () => {
  const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), maxReconnectDelay);
  reconnectAttempts++;
  
  setTimeout(() => {
    socket.connect();
  }, delay);
});

socket.on('connect', () => {
  reconnectAttempts = 0;
  // Re-authenticate on reconnect
  socket.emit('authenticate', { token: getToken() });
});

Offline Notifications

When a user reconnects after being offline, the server automatically sends all unread notifications created while offline via the notification:new event.

Request

  • Base URL
    http://localhost:3000
  • Auth
    none declared

Response

Default Response

documentationstring

Changes

No recorded changes to this operation across all 6 revisions of this API.