Skip to main content

Notifications

Notifications are in-app messages stored in the notification Cosmos DB container. They are separate from alerts: alerts dispatch content externally (email, SMS, push), while notifications are created as a side-effect of alert dispatch and are read back from the app. The endpoints below manage retrieval, FCM token registration, read-status updates, and assignee operations.

note

The date field in all responses is always current_user['nowUTCWithShiftDateTime'].strftime('%Y-%m-%dT%H:%M:%S%z') — the current server time expressed in the industry's shift-adjusted UTC offset.

GET /api/user/notification/ — All Notifications​

Returns all notifications for the authenticated industry, optionally scoped to a recent window of days.

GET /api/user/notification/?days=7
Authorization: Bearer <access_token>

Parameters​

ParameterRequiredDefaultDescription
daysNo0Number of recent days to include. 0 returns all records with no date filter

Execution flow​

info
  1. days defaults to 0 if the parameter is absent or not sent.
  2. NotificationService({days}).get_all_notifications() queries the notification container filtered by industryId from current_user. When days > 0, the query adds a recency filter for the last N days.
  3. NotificationDataFormatter().format_all_notification(raw) shapes the records into the response structure.

Response​

If the formatted result is non-empty:

HTTP 200
{
  "status": "success",
  "notifications": [ { ... }, { ... } ],
  "date": "2024-11-09T10:30:00+0530"
}

If the formatted result is empty:

HTTP 201
{
  "status": "success",
  "notifications": [],
  "date": "2024-11-09T10:30:00+0530"
}
note

The 201 status on an empty result is intentional — it signals "success with no content" rather than an error condition.

GET /api/user/notificationRange — Range Query​

Returns notifications between two explicit dates.

GET /api/user/notificationRange?startDate=01/11/2024&endDate=09/11/2024
Authorization: Bearer <access_token>

Parameters​

ParameterRequiredDefaultDescription
startDateYes—Start of the range (DD/MM/YYYY)
endDateYes—End of the range (DD/MM/YYYY)

Validation​

CheckError
startDate absent1403 "'startDate' missing"
endDate absent1403 "'endDate' missing"

Execution flow​

info

NotificationService({startDate, endDate}).get_range_notifications() queries the container for records in the inclusive date window. The result is processed by the same NotificationDataFormatter().format_all_notification() call and returns the same 200 / 201 response shape as the all-notifications endpoint.

POST /api/user/notification/register/fcm — Register FCM Token​

Registers a Firebase Cloud Messaging token for the current user's device. Tokens registered here are later batch-fetched by DatabaseSupporter.get_fcm_ids() when the alert dispatcher builds its FCM recipient set.

POST /api/user/notification/register/fcm
Authorization: Bearer <access_token>
X-Device-Id: device-abc123
Content-Type: application/json

{
  "fcmToken": "eHhO9..."
}

Headers​

HeaderRequiredDescription
AuthorizationYesBearer JWT
X-Device-IdYesUnique identifier for the calling device

Body fields​

FieldRequiredDescription
fcmTokenYesThe FCM registration token from the Firebase client SDK

Validation​

CheckError
fcmToken absent from body1403 "'fcmToken' missing"
X-Device-Id header absent1403 "'X-Device-Id' missing"

Execution flow​

info

NotificationService(args).register_fcm_user(args) writes the token to the user's record in Cosmos DB, keyed by X-Device-Id. If a token already exists for that device ID it is overwritten.

On exception → 400 with the error message from the caught exception.

Response​

HTTP 200
{
  "status": "success",
  "message": "FCM token registered successfully"
}

PATCH /api/user/notification/updateRead — Mark Notifications as Read​

Updates the read status of one or more notifications. This endpoint is PATCH, not PUT.

PATCH /api/user/notification/updateRead
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "notifications": [
    { "id": "notif-001", "read": true },
    { "id": "notif-002", "read": true }
  ]
}

Body​

Validated against NotificationReadUpdateRequest.

FieldRequiredDescription
notificationsYesArray of notification objects. Each object must contain enough identity information for the service to locate the Cosmos DB document

Execution flow​

info

NotificationService(args).update_notification_read_status(body['notifications']) patches each document in the notification container. Only documents whose industryId matches the authenticated user's industry can be updated.

Response​

HTTP 200
{
  "status": "success",
  "message": "notifications updated successfully"
}

POST /api/user/notification/assignee — Assign a Notification​

Assigns a notification to another user. After the database update, a WebSocket broadcast is sent to the industry's admin channel to inform the assignee in real time.

POST /api/user/notification/assignee
Authorization: Bearer <access_token>
Content-Type: application/json

Body​

Validated against NotificationAssigneeModel.

FieldRequiredDescription
assigneeIdYesUser ID of the person being assigned
notificationIdYesID of the notification to assign
(additional fields)VariesOther fields required by NotificationAssigneeModel

Execution flow​

info
  1. NotificationService(args).add_notification_assignee(body) writes the assignment to the notification document in Cosmos DB.
  2. AdminNotificationService().send_web_socket_notification('Notification Assigned', f'{current_user["userId"]} assigned an alert to {body["assigneeId"]}') broadcasts the event over Azure Web PubSub. This is a fire-and-forget broadcast — it is not stored as a separate notification document.

Response​

HTTP 200
{
  "status": "success",
  "message": "Assignee added successfully"
}

DELETE /api/user/notification/assignee — Remove Assignee​

Removes an existing assignee from a notification.

DELETE /api/user/notification/assignee
Authorization: Bearer <access_token>
Content-Type: application/json

Execution flow​

info

NotificationService(args).delete_notification_assignee(body) clears the assignee field from the notification document in Cosmos DB. No WebSocket broadcast is sent on removal.

Response​

HTTP 200
{
  "status": "success",
  "message": "Assignee deleted successfully"
}

PATCH /api/user/notification/assignee — Mark as Resolved​

Marks a notification as resolved. Uses PATCH on the same /assignee path as the DELETE and POST endpoints, distinguished by HTTP method.

PATCH /api/user/notification/assignee
Authorization: Bearer <access_token>
Content-Type: application/json

Execution flow​

info

NotificationService(args).update_notification_as_resolved(body) sets the resolved flag on the notification document in Cosmos DB.

Response​

HTTP 200
{
  "status": "success",
  "message": "notifications marked as resolved successfully"
}

Status Code Reference​

CodeMeaning
200Operation succeeded
201Success — no notifications found for the given query
400Exception during FCM registration
401Missing or invalid JWT
1403Missing required parameter (startDate, endDate, fcmToken, or X-Device-Id)