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:
- Connect to WebSocket server
- Emit authenticate event with JWT token
- 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 URLhttp://localhost:3000
- Authnone declared
Response
Default Response
Changes
No recorded changes to this operation across all 6 revisions of this API.