---
title: "GET /api/v1/notifications/websocket-docs"
method: GET
path: "/api/v1/notifications/websocket-docs"
tags: ["notifications", "websocket"]
---

# GET /api/v1/notifications/websocket-docs

`GET /api/v1/notifications/websocket-docs`

## Request

- Base URL: `http://localhost:3000`
- URL: `http://localhost:3000/api/v1/notifications/websocket-docs`
- Auth: none declared

## 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`

```javascript
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

```javascript
// 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:

```javascript
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.

## Response `200`

Default Response

- object
  - `documentation` string

---

[API](https://skmtc.dev/farmersonly/apis/farmersonly-club-api.md) - [All operations](https://skmtc.dev/farmersonly/apis/farmersonly-club-api/llms.txt) - [OpenAPI document](https://skmtc.dev/farmersonly/apis/farmersonly-club-api/revisions/b4fa9123ba90?raw)
