Notifications

Manage user notifications across multiple channels.

Multi-Channel Delivery

Send notifications via push, email, and SMS with priority-based routing, user preference management, and delivery tracking.

Overview

The Notification Service supports:

Push notifications
Email notifications
SMS notifications (coming soon)
In-app notifications
Notification preferences

Base Path: /v1/notifications

Get Notifications

Get All Notifications

GET /v1/notifications

Parameter	Type	Description
page	number	Page number
limit	number	Results per page (max: 50)
type	string	Filter by type
read	boolean	Filter by read status

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "notif_123",
      "userId": "user_456",
      "type": "trade_update",
      "title": "Trade Target Reached",
      "message": "Your EUR/USD trade hit the target price of 1.0950",
      "priority": "high",
      "read": false,
      "channels": ["push", "email"],
      "metadata": {
        "tradeId": "trade_789",
        "symbol": "EUR/USD",
        "profitLoss": 100.00
      },
      "createdAt": "2025-10-21T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Get Unread Count

GET /v1/notifications/unread-count

{
  "success": true,
  "status": 200,
  "data": {
    "count": 12
  }
}

Mark as Read

Mark Single Notification

PUT /v1/notifications/:notificationId/read

Mark All as Read

PUT /v1/notifications/read-all

{
  "success": true,
  "status": 200,
  "message": "15 notifications marked as read",
  "data": {
    "count": 15
  }
}

Delete Notification

DELETE /v1/notifications/:notificationId

Send Notification (Admin)

Send Single Notification

POST /v1/notifications/send

{
  "userId": "user_456",
  "type": "announcement",
  "title": "New Feature Released!",
  "message": "Check out our new AI trading assistant",
  "priority": "medium",
  "channels": ["push", "email"],
  "metadata": {
    "featureId": "ai-assistant",
    "url": "/intelligence"
  }
}

Send Bulk Notifications

POST /v1/notifications/send-bulk

{
  "userIds": ["user_123", "user_456", "user_789"],
  "notification": {
    "type": "announcement",
    "title": "Platform Maintenance",
    "message": "Scheduled maintenance on Sunday 2AM-4AM UTC",
    "priority": "high",
    "channels": ["push", "email"]
  }
}

Notification Types

Type	Description	Default Priority	Default Channels
`welcome`	Welcome message	medium	email, push
`trade_update`	Trade status changes	high	push, email
`achievement`	Milestones reached	low	push
`course_update`	Course/lesson updates	medium	email
`comment_reply`	Comment on post	medium	push
`announcement`	Platform announcements	high	push, email
`reminder`	Scheduled reminders	medium	push
`alert`	Important alerts	critical	push, email, sms

Priority Levels

Priority	Delivery	Examples
`critical`	Immediate, all channels	Account security, payment issues
`high`	Within 5 minutes	Trade alerts, target reached
`medium`	Within 30 minutes	Course updates, new comments
`low`	Batched hourly	Achievements, milestones

Channels

Push Notifications

Delivered to:

Mobile apps (iOS, Android)
Web browsers (with permission)
Desktop applications

Format:

{
  "title": "Trade Target Reached",
  "body": "EUR/USD hit 1.0950",
  "icon": "https://cdn.yourdomain.com/icons/trade.png",
  "badge": "https://cdn.yourdomain.com/badge.png",
  "data": {
    "tradeId": "trade_789",
    "action": "view_trade"
  }
}

Email Notifications

Delivered to user's registered email.

Templates:

Welcome email
Trade alerts
Course notifications
Weekly summaries
Platform announcements

SMS Notifications (Coming Soon)

For critical alerts only.

Notification Preferences

Users can configure preferences:

{
  "preferences": {
    "email": {
      "enabled": true,
      "types": ["trade_update", "announcement"]
    },
    "push": {
      "enabled": true,
      "types": ["trade_update", "comment_reply", "alert"]
    },
    "sms": {
      "enabled": false,
      "types": ["alert"]
    }
  }
}

Code Examples

React Notification Bell

function NotificationBell() {
  const [notifications, setNotifications] = useState([]);
  const [unreadCount, setUnreadCount] = useState(0);

  useEffect(() => {
    fetchNotifications();
    fetchUnreadCount();
    
    // Poll for new notifications
    const interval = setInterval(fetchUnreadCount, 30000);
    return () => clearInterval(interval);
  }, []);

  const fetchNotifications = async () => {
    const response = await fetch('/v1/notifications?limit=10', {
      headers: {
        'X-API-Key': apiKey,
        'Authorization': `Bearer ${token}`
      }
    });

    const { data } = await response.json();
    setNotifications(data);
  };

  const fetchUnreadCount = async () => {
    const response = await fetch('/v1/notifications/unread-count', {
      headers: {
        'X-API-Key': apiKey,
        'Authorization': `Bearer ${token}`
      }
    });

    const { data } = await response.json();
    setUnreadCount(data.count);
  };

  const markAsRead = async (notificationId) => {
    await fetch(`/v1/notifications/${notificationId}/read`, {
      method: 'PUT',
      headers: {
        'X-API-Key': apiKey,
        'Authorization': `Bearer ${token}`
      }
    });

    fetchNotifications();
    fetchUnreadCount();
  };

  return (
    <div>
      <button>
        🔔 {unreadCount > 0 && <span>{unreadCount}</span>}
      </button>
      
      <div className="dropdown">
        {notifications.map(notif => (
          <div 
            key={notif.id}
            onClick={() => markAsRead(notif.id)}
            className={notif.read ? '' : 'unread'}
          >
            <strong>{notif.title}</strong>
            <p>{notif.message}</p>
            <small>{formatTime(notif.createdAt)}</small>
          </div>
        ))}
      </div>
    </div>
  );
}

Realtime API - Real-time notifications via WebSocket
Events - Which events trigger notifications
User Preferences - Configure notification settings

Notifications

On this page