Notification WebSocket API Documentation

Overview

This document explains the functionality of the NotificationConsumer WebSocket API used to handle notifications in real-time for the vendor. The WebSocket API allows clients to receive, mark as read, and load notifications in a categorized and paginated manner. The WebSocket endpoint is available at ws://<host>/v1/ws/notifications/.

---

WebSocket Endpoints and Actions

Notification WebSocket Consumer

Endpoint	HTTP Method	Action	Description	Permissions
ws/v1/ws/notifications/	WebSocket	connect	Establish a WebSocket connection to receive notifications.	IsAuthenticated
		disconnect	Close the WebSocket connection when the client disconnects.	IsAuthenticated
		receive	Receive messages from the client (e.g., mark notifications as read, load more notifications).	IsAuthenticated
		reload_unread_notifications	Reload unread notifications when prompted.	IsAuthenticated

---

NotificationConsumer Explanation

1. connect

• Purpose: Establish a WebSocket connection and authenticate the user based on a token passed in the URL query parameters.
• Implementation:
• The token is extracted from the query string and used to authenticate the user.
• If the token is invalid or expired, the connection is closed with an error code 4001.
• The user’s role is checked, and permissions are validated (vendor roles are verified if the user is a vendor).
• The connection is added to two WebSocket groups: one specific to the user (notifications_{user_id}) and one global group (all_notifications).
• After a successful connection, unread notifications are loaded and sent to the client.

2. disconnect

• Purpose: Disconnect the WebSocket connection and remove the user from the WebSocket groups.
• Implementation:
• The user’s channel is removed from both the user-specific and the global notification groups.
• The connection is closed gracefully.

3. receive

• Purpose: Receive actions from the client such as marking notifications as read or loading more notifications.
• Actions:
• mark_read: Marks a specific notification as read.
  • Sends the notification ID to mark as read.
  • Responds with the status of the operation.
• load_more: Loads additional notifications for pagination purposes.
  • Fetches more notifications based on the current page.
  • Returns the notifications grouped by category.

4. reload_unread_notifications

• Purpose: Reload unread notifications when triggered by a WebSocket event.
• Implementation:
• Fetches unread notifications and sends them to the client in a categorized format.

5. load_unread_notifications

• Purpose: Fetch and send unread notifications categorized by their respective notification categories.
• Implementation:
• Retrieves unread notifications associated with the authenticated user and groups them by category.
• Returns a JSON response with all unread notifications, categorized, to the client.

6. load_more_notifications

• Purpose: Fetch and send more notifications based on pagination (page-wise).
• Implementation:
• Retrieves a paginated set of notifications, grouped by category.
• Allows the client to request more notifications as they scroll.

7. mark_notification_as_read

• Purpose: Mark a specific notification as read and update its status.
• Implementation:
• Accepts the notification ID and marks it as read in the database.
• Sends a response back to the client confirming the operation.

---

Database Sync Methods

1. get_user_from_token

• Purpose: Retrieves the user object from the access token.
• Implementation:
• Decodes the provided JWT access token and validates it.
• Fetches the user associated with the token.

2. get_vendor

• Purpose: Retrieves the vendor associated with the authenticated user.
• Implementation:
• Fetches the vendor object based on the user’s information.

3. get_unread_recent_notifications

• Purpose: Retrieves unread notifications for the authenticated vendor.
• Implementation:
• Filters notifications based on the vendor’s permissions and fetches unread, recent notifications.

4. get_paginated_notifications

• Purpose: Retrieves a paginated set of notifications.
• Implementation:
• Returns a specific number of notifications per page, grouped by category.

5. update_notification_read_status

• Purpose: Marks a notification as read.
• Implementation:
• Updates the is_read and is_recent_notification fields of the specified notification.

6. has_vendor_role_permission

• Purpose: Verifies if the vendor role has permission to access notifications.
• Implementation:
• Checks if the authenticated vendor has the necessary permissions to access notifications based on their sub-vendor roles.

---

Permissions

The WebSocket API requires that the user be authenticated, and additional role-based permissions may apply based on the user’s role: - Vendor: Can access and manage their own notifications. - Vendor Role: Specific permissions are checked to ensure the user has access to notifications. - User: Cannot access notifications.

---

Example WebSocket Messages

1. Initial Connection Response

Upon a successful connection, the WebSocket client will receive the unread notifications in a categorized format:

{
  "action": "unread_notifications",
  "notifications": {
    "Order Notifications": [
      {
        "id": 1,
        "vendor": 123,
        "message": "Order #123 has been placed.",
        "context_data": "{}",
        "is_read": false,
        "readed_at": null,
        "created_at": "12-03-2025 10:15:00"
      }
    ],
    "General Notifications": [
      {
        "id": 2,
        "vendor": 123,
        "message": "You have a new general notification.",
        "context_data": "{}",
        "is_read": false,
        "readed_at": null,
        "created_at": "12-03-2025 11:00:00"
      }
    ]
  }
}