The notifications API allows you to send real-time notifications to users through WebSocket connections. Notifications can be scoped to specific users or devices and support multiple severity levels.
Send notification
POST /api/notifications/send Send a notification to users via WebSocket
Authentication Requires notifications permission.
Request body Notification severity level Options: info, success, warning, error, emergency
Notification title displayed prominently
Detailed notification message content
Target a specific user by ID. If omitted and user is not a superuser, notification is sent only to the authenticated user.
Associate the notification with a specific device
Whether the user can dismiss the notification
Additional custom data to include with the notification Example: { "actionId" : "action123" , "timestamp" : "2024-03-20T10:30:00Z" }
Response Indicates whether the notification was sent successfully
Unique identifier for the sent notification
Number of active WebSocket clients that received the notification
Error message if the notification failed to send
Example: Send info notification curl -X POST http://localhost:8000/api/notifications/send \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "info", "title": "Device Connected", "message": "Device Camera-01 has successfully connected", "deviceId": "device123" }'
Response: { "success" : true , "notificationId" : "notif_abc123" , "recipientCount" : 3 }
Example: Send error notification curl -X POST http://localhost:8000/api/notifications/send \ -H "X-API-Key: dev-api-key-12345" \ -H "Content-Type: application/json" \ -d '{ "type": "error", "title": "Action Failed", "message": "Failed to execute capture action: Connection timeout", "deviceId": "device123", "dismissible": true, "metadata": { "actionName": "capture", "errorCode": "TIMEOUT" } }'
Response: { "success" : true , "notificationId" : "notif_xyz789" , "recipientCount" : 1 }
Example: Send user-specific notification curl -X POST http://localhost:8000/api/notifications/send \ -H "Authorization: Bearer SUPERUSER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "success", "title": "Task Completed", "message": "Your scheduled task has completed successfully", "userId": "user456" }'
Notification types info General informational messages about system status or activities.
success Positive confirmation messages for successful operations.
warning Cautionary messages about potential issues that don’t prevent operation.
error Error messages about failed operations or problems requiring attention.
emergency Critical alerts requiring immediate attention.
WebSocket connection To receive notifications, clients must establish a WebSocket connection:
const ws = new WebSocket ( 'ws://localhost:8000/notifications' ); ws . onopen = () => { console . log ( 'Connected to notification stream' ); }; ws . onmessage = ( event ) => { const notification = JSON . parse ( event . data ); console . log ( 'Received notification:' , notification ); }; ws . onerror = ( error ) => { console . error ( 'WebSocket error:' , error ); }; ws . onclose = () => { console . log ( 'Disconnected from notification stream' ); };
Notifications received via WebSocket have the following structure:
{ "id" : "notif_abc123" , "type" : "error" , "title" : "Action Failed" , "message" : "Failed to execute capture action: Connection timeout" , "userId" : "user123" , "deviceId" : "device456" , "dismissible" : true , "metadata" : { "actionName" : "capture" , "errorCode" : "TIMEOUT" }, "timestamp" : "2024-03-20T10:30:00Z" }
User targeting Superuser notifications Superusers can send notifications to any user by specifying the userId field.
Regular user notifications Regular users can only send notifications to themselves. The userId field is automatically set to the authenticated user’s ID.
Broadcast notifications Superusers can omit the userId field to broadcast notifications to all connected clients.
Error responses 401 Unauthorized { "error" : "Authentication required" }
403 Forbidden { "error" : "Missing required permissions: notifications" }
500 Internal server error { "error" : "Failed to send notification" }