WebSocket API documentation for the Aphrodite Notification Service using Socket.io.
WebSocket URL: wss://ws.aphrodite.example.com Namespace:
/notifications Port: 7003 Protocol: Socket.io v4
Table of Contents#
Connection#
Establishing Connection#
import { io } from 'socket.io-client';
const socket = io('wss://ws.aphrodite.example.com/notifications', {
auth: {
token: '<access_token>',
},
transports: ['websocket'],
});
Connection Events#
Upon successful connection, the user is automatically subscribed to their
personal notification room: user:${userId}:notifications
socket.on('connect', () => {
console.log('Connected to notifications');
});
Notification Events#
Receive Notification#
Server Event: notification:received
Real-time notification pushed to connected clients.
socket.on('notification:received', (notification) => {
console.log('New notification:', notification);
});
Notification Payload:
{
"id": "notif_abc123",
"type": "new_follower",
"title": "New Follower",
"body": "johndoe started following you",
"icon": "https://cdn.aphrodite.example.com/avatars/usr_johndoe.jpg",
"data": {
"followerId": "usr_johndoe",
"followerUsername": "johndoe",
"followerDisplayName": "John Doe"
},
"actionUrl": "/profile/johndoe",
"priority": "normal",
"read": false,
"dismissed": false,
"createdAt": "2026-01-18T12:00:00.000Z"
}
Notification Types#
| Type | Description | Priority |
|---|---|---|
new_follower |
Someone followed you | normal |
new_subscriber |
Someone subscribed to you | high |
tip_received |
Received a tip | high |
stream_live |
Followed creator went live | high |
stream_reminder |
Scheduled stream starting soon | high |
stream_ended |
Stream has ended | low |
new_message |
New direct message | normal |
mention |
Mentioned in chat | normal |
content_published |
Creator published new content | normal |
subscription_expiring |
Subscription expiring soon | high |
subscription_renewed |
Subscription was renewed | normal |
payment_received |
Payment processed (creator) | high |
payout_completed |
Payout sent (creator) | high |
goal_completed |
Tip goal completed | high |
achievement_unlocked |
New achievement earned | normal |
moderation_action |
Moderation action on your account | urgent |
system |
System announcement | varies |
Notification Payload by Type#
new_follower#
{
"type": "new_follower",
"data": {
"followerId": "usr_johndoe",
"followerUsername": "johndoe",
"followerDisplayName": "John Doe",
"followerAvatarUrl": "..."
}
}
tip_received#
{
"type": "tip_received",
"data": {
"tipId": "tip_abc123",
"amount": 100,
"currency": "tokens",
"message": "Great stream!",
"senderId": "usr_tipper",
"senderUsername": "generoustipper",
"streamId": "str_xyz789",
"isAnonymous": false
}
}
stream_live#
{
"type": "stream_live",
"data": {
"streamId": "str_xyz789",
"creatorId": "usr_creator",
"creatorUsername": "favoritestreamer",
"title": "Saturday Night Stream",
"thumbnailUrl": "...",
"category": "Just Chatting"
}
}
new_message#
{
"type": "new_message",
"data": {
"conversationId": "conv_abc123",
"senderId": "usr_sender",
"senderUsername": "sender",
"preview": "Hey! Just wanted to say..."
}
}
Notification Management#
Get Notifications#
Client Emit: notification:get
socket.emit(
'notification:get',
{
filter: 'all', // 'all' | 'unread' | 'read'
cursor: null,
limit: 20,
},
(response) => {
console.log('Notifications:', response.notifications);
}
);
Server Response: notification:list
socket.on('notification:list', (data) => {
// {
// notifications: [...],
// pagination: { cursor: '...', hasMore: true },
// unreadCount: 5
// }
});
Get Unread Notifications#
Client Emit: notification:get-unread
socket.emit(
'notification:get-unread',
{
limit: 10,
},
(response) => {
console.log('Unread notifications:', response.notifications);
}
);
Server Response: notification:unread-list
socket.on('notification:unread-list', (data) => {
// {
// notifications: [...],
// unreadCount: 5
// }
});
Get Notification Stats#
Client Emit: notification:get-stats
socket.emit('notification:get-stats', {}, (response) => {
console.log('Stats:', response);
});
Server Response: notification:stats
socket.on('notification:stats', (data) => {
// {
// unreadCount: 5,
// byType: {
// new_follower: 2,
// tip_received: 1,
// stream_live: 2
// }
// }
});
Mark as Read#
Client Emit: notification:mark-read
socket.emit(
'notification:mark-read',
{
notificationId: 'notif_abc123',
},
(response) => {
console.log('Marked as read:', response.success);
}
);
Server Response: notification:marked-read
socket.on('notification:marked-read', (data) => {
// {
// notificationId: 'notif_abc123',
// readAt: '2026-01-18T12:05:00.000Z',
// unreadCount: 4
// }
});
Mark All as Read#
Client Emit: notification:mark-all-read
socket.emit('notification:mark-all-read', {}, (response) => {
console.log('All marked as read:', response.success);
});
Server Response: notification:all-marked-read
socket.on('notification:all-marked-read', (data) => {
// {
// count: 5,
// readAt: '2026-01-18T12:05:00.000Z'
// }
});
Dismiss Notification#
Client Emit: notification:dismiss
socket.emit(
'notification:dismiss',
{
notificationId: 'notif_abc123',
},
(response) => {
console.log('Dismissed:', response.success);
}
);
Server Response: notification:dismissed
socket.on('notification:dismissed', (data) => {
// { notificationId: 'notif_abc123' }
});
Delete Notification#
Client Emit: notification:delete
socket.emit(
'notification:delete',
{
notificationId: 'notif_abc123',
},
(response) => {
console.log('Deleted:', response.success);
}
);
Server Response: notification:deleted
socket.on('notification:deleted', (data) => {
// { notificationId: 'notif_abc123' }
});
Preferences#
Get Preferences#
Client Emit: notification:get-preferences
socket.emit('notification:get-preferences', {}, (response) => {
console.log('Preferences:', response.preferences);
});
Server Response: notification:preferences
socket.on('notification:preferences', (data) => {
console.log('Notification preferences:', data);
});
Preferences Payload:
{
"preferences": {
"channels": {
"inApp": { "enabled": true },
"push": { "enabled": true },
"email": { "enabled": true, "frequency": "instant" }
},
"types": {
"new_follower": { "inApp": true, "push": true, "email": false },
"tip_received": { "inApp": true, "push": true, "email": true },
"stream_live": { "inApp": true, "push": true, "email": false },
"new_message": { "inApp": true, "push": true, "email": false },
"subscription_expiring": { "inApp": true, "push": true, "email": true }
},
"quiet_hours": {
"enabled": true,
"start": "23:00",
"end": "08:00",
"timezone": "America/New_York"
},
"bundling": {
"enabled": true,
"interval": 300
}
}
}
Update Preferences#
Client Emit: notification:update-preferences
socket.emit(
'notification:update-preferences',
{
types: {
new_follower: { push: false },
},
quiet_hours: {
enabled: true,
start: '22:00',
end: '09:00',
},
},
(response) => {
console.log('Updated:', response.success);
}
);
Server Response: notification:preferences-updated
socket.on('notification:preferences-updated', (data) => {
// { preferences: {...}, updatedAt: '...' }
});
Subscriptions#
Subscribe to Channel#
Subscribe to additional notification channels (beyond personal notifications).
Client Emit: notification:subscribe
socket.emit(
'notification:subscribe',
{
channel: 'creator:usr_xyz789', // Subscribe to creator's announcements
},
(response) => {
console.log('Subscribed:', response.success);
}
);
Channel Types:
| Channel Pattern | Description |
|---|---|
creator:{creatorId} |
Creator announcements |
stream:{streamId} |
Stream notifications (goals, events) |
system |
Platform-wide announcements |
Unsubscribe from Channel#
Client Emit: notification:unsubscribe
socket.emit(
'notification:unsubscribe',
{
channel: 'creator:usr_xyz789',
},
(response) => {
console.log('Unsubscribed:', response.success);
}
);
Push Notification Registration#
Register Push Token#
Client Emit: notification:register-push
socket.emit(
'notification:register-push',
{
token: '<fcm_token>',
platform: 'web', // 'web' | 'ios' | 'android'
deviceId: 'device_abc123',
},
(response) => {
console.log('Registered:', response.success);
}
);
Unregister Push Token#
Client Emit: notification:unregister-push
socket.emit(
'notification:unregister-push',
{
token: '<fcm_token>',
},
(response) => {
console.log('Unregistered:', response.success);
}
);
Data Types#
Notification Object#
interface Notification {
id: string;
type: NotificationType;
title: string;
body: string;
icon?: string;
imageUrl?: string;
data: Record<string, unknown>;
actionUrl?: string;
actions?: NotificationAction[];
priority: 'low' | 'normal' | 'high' | 'urgent';
read: boolean;
readAt?: string;
dismissed: boolean;
dismissedAt?: string;
expiresAt?: string;
createdAt: string;
}
Notification Action#
interface NotificationAction {
id: string;
label: string;
url?: string;
action?: string;
}
Notification Preferences#
interface NotificationPreferences {
channels: {
inApp: { enabled: boolean };
push: { enabled: boolean };
email: { enabled: boolean; frequency: 'instant' | 'daily' | 'weekly' };
};
types: Record<
NotificationType,
{ inApp: boolean; push: boolean; email: boolean }
>;
quiet_hours?: {
enabled: boolean;
start: string;
end: string;
timezone: string;
};
bundling?: {
enabled: boolean;
interval: number;
};
}
Document History#
| Date | Version | Changes |
|---|---|---|
| 2026-01-18 | 1.0.0 | Initial Notification WebSocket API docs |