Notifications & Messaging API
System notifications and admin/provider messaging endpoints
1. Purpose
This document defines the Notifications and Messaging API endpoints for:
- System notifications (push, SMS, email)
- Manual messaging from Admin/Provider to customers
- Notification read status management
All endpoints follow the conventions in api-principles-and-versioning.md.
3. Notifications API
3.1 Get User Notifications
/api/v1/notificationsAuth: Bearer token required
Roles: CUSTOMER / END_USER
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter: read / unread / all (default: all) |
| type | string | Filter by type: booking_update, payment_update, trip_status, rating_request, general |
| page | integer | Page number (default: 1) |
| per_page | integer | Items per page (default: 20) |
3.2 Mark Notification as Read
/api/v1/notifications/{id}/readAuth: Bearer token required
Roles: CUSTOMER / END_USER
Additional: User must own the notification
3.3 Mark All Notifications as Read
/api/v1/notifications/read-allAuth: Bearer token required
Roles: CUSTOMER / END_USER
3.4 Get Unread Count
/api/v1/notifications/unread-countAuth: Bearer token required
Roles: CUSTOMER / END_USER
4. Messaging API (Admin/Provider → Customer)
4.1 Send Message to Customer
/api/v1/messagesAuth: Bearer token required
Roles: ADMIN, SUPER_ADMIN, PROVIDER_ADMIN, SUPPORT_AGENT
Validation Rules:
- receiver_id: required, must exist
- booking_id: optional, must belong to receiver if provided
- subject: required, max 120 characters
- body: required
Behavior:
- Message is stored in database
- Notification is created for the receiver
- Delivery attempted via configured channels (Push, SMS, Email)
4.2 Get Sent Messages (Admin/Provider)
/api/v1/messages/sentAuth: Bearer token required
Roles: ADMIN, SUPER_ADMIN, PROVIDER_ADMIN
| Parameter | Type | Description |
|---|---|---|
| booking_id | integer | Filter by booking |
| page | integer | Page number |
Provider users only see messages they sent; Admin sees all.
5. System Notification Triggers (Internal)
These notifications are triggered automatically by the backend:
| Trigger Event | Notification Type | Template (Arabic) |
|---|---|---|
| Payment success | payment_update | تم تأكيد الدفع بنجاح |
| Booking confirmed | booking_update | تم تأكيد حجزك بنجاح |
| Booking cancelled | booking_update | تم إلغاء حجزك |
| Trip reminder (24h before) | trip_status | رحلتك تبدأ غداً |
| Trip completed | trip_status | نتمنى لك رحلة سعيدة |
| Rating request | rating_request | نرجو تقييم رحلتك |
| Refund processed | payment_update | تم استرداد المبلغ |
6. Error Cases
| Error Code | HTTP | Description |
|---|---|---|
| NOTIFICATION_NOT_FOUND | 404 | Notification does not exist |
| NOTIFICATION_ACCESS_DENIED | 403 | User does not own this notification |
| MESSAGE_RECEIVER_NOT_FOUND | 404 | Receiver user not found |
| MESSAGE_BOOKING_MISMATCH | 400 | Booking does not belong to receiver |
| MESSAGE_SUBJECT_TOO_LONG | 422 | Subject exceeds 120 characters |
7. Delivery Channels
Notifications can be delivered through multiple channels:
| Channel | Technology | Use Case |
|---|---|---|
| Push | Firebase Cloud Messaging | Mobile app notifications |
| SMS | TBD (Taqnyat, Unifonic, etc.) | Critical updates, OTP |
| TBD (SendGrid, Mailgun, etc.) | Receipts, confirmations |
Channel selection is configured at the backend level and may vary by notification type.
8. Cross-References
Related Entities:
Notification, Message, User, Booking
Related Screens:
إشعارات (Mobile), إرسال رسالة للعميل (Admin/Provider)
Related APIs:
auth-and-users-api.md, trips-and-bookings-api.md
Related Rules:
BR-1 to BR-7 in notifications-and-messaging-module.md
Related Roles:
CUSTOMER, ADMIN, SUPER_ADMIN, PROVIDER_ADMIN, SUPPORT_AGENT