---
feature: Notifications and FCM Push Delivery
slug: notifications
surface: delivery
consumer: flutter
version: 1.5.0
status: ready
brd_version: "1.3"
brd_ids: [DRIV-018]
business_rules: [BR-16, BR-17, BR-18, BR-22]
decisions: [DEC-13, TD-19, TD-23, TD-25, TD-141, TD-142, TD-143, TD-166, TD-167]
schema_tables: [notifications, notification_deliveries, devices, device_apps]
screens: [driver--notifications--*]
related_docs: [auth.md, trip-requests.md, trip-execution.md, ../API_CONVENTIONS.md]
last_updated: 2026-11-08
---

# Notifications — Flutter Integration Guide (delivery)

> **Base URL:** `{HOST}/api/v1` · Shared rules (headers, envelope, errors, pagination): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.5.0 | 2026-11-08 | MINOR | New event `driver_nearby_demand`: while offline, she is invited to go online when trips wait in her districts (TD-174). | Show it with the motorbike icon; a tap may open the home screen's online switch. |
| 1.4.0 | 2026-11-08 | MINOR | New inbox event `general`: a notification an admin sent from the dashboard (TD-173). | Show it as a plain inbox item; a tap may open the inbox. |
| 1.3.1 | 2026-11-04 | PATCH | Fix: a template switched off no longer hides notifications already in the inbox; only `send_in_app = 0` hides rows (TD-168). Section 5 open items are current. | None. |
| 1.3.0 | 2026-11-04 | MINOR | Added missing BRD scenarios (`trip_completed`, `earning_recorded`, `account_document_expiring`, `driver_rated`); driver trip acceptance alert; inactive templates filtered from inbox. | Handle new event keys in deep link / routing handlers if needed. |
| 1.2.0 | 2026-11-04 | MINOR | Dynamic placeholder template engine; and in-app delivery audit records. | None. |
| 1.1.0 | 2026-11-04 | MINOR | Per-category push / SMS switches (`GET` / `PUT …/notifications/preferences/categories`), event catalog, device lifecycle, inbox success examples. | Build the notification settings screen; send `device_token` on logout. |
| 1.0.0 | 2026-10-28 | Initial | Device registration, shared inbox and FCM delivery of persisted notifications. | Register the device token after login and on token refresh. |

## Changelog

### 1.5.0 — 2026-11-08

- **Added:** event `driver_nearby_demand` ("Delivery requests near you", `driver--notifications--01-inbox.png`). Sent while she is **offline** when at least `driver_nearby_alert_min_trips` (dashboard setting, default 1) trips are searching for a driver and would be offered to her if she were online: approved, active vehicle, not on a trip, covering the trip's district. At most once per `driver_nearby_alert_cooldown_minutes` (default 60). Nothing is reserved: going online only makes her eligible for the next offers (BR-16, BR-17).
  - Example: title `طلبات توصيل قريبة منك`, body `يوجد 3 طلبات نشطة في حي الملقا — فعّلي حالة الاتصال لاستقبالها.` (`منطقتك` when the order has no district).
  - `data` = `{"count": 3, "district_id": "<uuid or null>"}`; in the push every value is a string.
  - Category `orders`: switching orders off mutes its push; the inbox row is always written. The admin can switch the template off.
- **Breaking:** No.
- **App action required:** Show it like the design (motorbike icon). A tap can open the home screen so she can go online.

### 1.4.0 — 2026-11-08

- **Added:** event `general` in this app's inbox and push. An admin wrote it in the dashboard and sent it to every reachable driver (approved accounts only), to those in chosen cities, or to people she picked (TD-173). `title` and `body` are the admin's text in the user's language (Arabic when no English was written). `data` = `{"broadcast_id": "<uuid>"}`. Category `offers`: switching offers off mutes its push; the inbox row is always written.
- **Breaking:** No.
- **App action required:** Show `general` as a plain inbox item. The inbox designs have no offer card for this app; show it with the generic bell icon. Nothing to call: no endpoint changed.

### 1.3.1 — 2026-11-04

- **Fixed:** switching a template off (`is_active = false`) stops new notifications but no longer hides ones already in the inbox, so the history and `unread_count` stay stable. Rows of a template with `send_in_app = 0` are still hidden (they exist only to carry the push).
- **Breaking:** No. **App action required:** None.

### 1.3.0 — 2026-11-04
- **Added:** New notification scenarios for driver app: `trip_completed` (trip delivery completed), `earning_recorded` (trip delivery fee earnings recorded), `account_document_expiring` (approved driver document nearing expiry via `documents:alert-expiring`), and `driver_rated` (provider rating received).
- **Changed:** Driver profile creation dispatches `user_registered`; trip acceptance dispatches `trip_driver_accepted` to the driver as well as provider; inactive or `send_in_app = false` templates filtered from inbox.
- **Breaking:** No.
- **App action required:** Handle new event keys in push/inbox routing handlers if needed.
- **BRD / decisions:** DRIV-018, ADMIN-020, TD-167.

### 1.2.0 — 2026-11-04
- **Added:** Dynamic placeholder-based notification templating (TD-167); `in_app` delivery audit logging.
- **Changed:** Notification copy now uses customizable admin templates with locale resolution.
- **Breaking:** No.
- **App action required:** None.
- **BRD / decisions:** DRIV-018, DEC-13, DEC-15, TD-167.

### 1.1.0 — 2026-11-04
- **Added:** `GET` and `PUT /api/v1/delivery/notifications/preferences/categories` (TD-166); the shared event catalog, push format and device lifecycle in [API_CONVENTIONS §7.1–§7.3](../API_CONVENTIONS.md); captured examples for the inbox routes. The push sender now honours every category switch (before, only `chat` was checked).
- **Changed / removed:** None. Nothing existing was renamed or removed.
- **Breaking:** No. **App action required:** add the settings screen; send `device_token` when logging out (DEC-29).
- **BRD / decisions:** DRIV-018, DEC-13, TD-166; open: DEC-28, DEC-29.

### 1.0.0 — 2026-10-28
- **Added:** Device registration, shared inbox and FCM delivery of persisted notifications (TD-141–143).
- **App action required:** Register the device token after login and when it rotates.
- **BRD / decisions:** DRIV-018, DEC-13, TD-23, TD-25, TD-141–143.

## 1. Business summary

The driver app can register a push token and access its persisted notification inbox. The broader event catalog and notification preferences UI contract are not complete.

## 2. User flow and screens

Register the device after login, list the inbox, and open a notification to mark it read. The shared inbox is scoped to the signed-in user and token app.

## 3. Endpoints

All routes require an active authenticated account and a bearer token for this app. Paths below include the `/api/v1` prefix. Set `Accept-Language: ar|en` as needed.

| Method | Path | Route name | Behavior and example |
|--------|------|------------|----------------------|
| `POST` | `/api/v1/delivery/notifications/device` | `delivery.notifications.device` | Register or refresh the device. Postman: `delivery.notifications.device` › "200 Device". |
| `GET` | `/api/v1/delivery/notifications/preferences/categories` | `delivery.notifications.preferences.categories.show` | Read the five category switches of this app. Postman: `delivery.notifications.preferences.categories.show` › "200 Driver defaults". |
| `PUT` | `/api/v1/delivery/notifications/preferences/categories` | `delivery.notifications.preferences.categories.update` | Partial update. Postman: `delivery.notifications.preferences.categories.update` › "200 Driver switches offers off". |
| `GET` | `/api/v1/notifications` | `shared.notifications.index` | List notifications and unread count. Example: see below. |
| `GET` | `/api/v1/notifications/{id}` | `shared.notifications.show` | Read a notification by UUID and mark it read. Example: see below. |
| `DELETE` | `/api/v1/notifications/{id}` | `shared.notifications.destroy` | Delete one notification by UUID. Example: see below. |
| `POST` | `/api/v1/notifications/mark-all-read` | `shared.notifications.mark-all-read` | Mark all as read. Example: see below. |
| `DELETE` | `/api/v1/notifications/clear-all` | `shared.notifications.clear-all` | Clear the inbox. Example: see below. |

Device registration requires `device_token` (string, maximum 4096 characters) and `device_type` (`ios`, `android`, or `huawei`); `app_version` is optional (string, maximum 20 characters) and `device_id` is prohibited.

Device response (Postman: `delivery.notifications.device` › "200 Device"):

```json
{
    "status": "success",
    "message": "Device registered.",
    "data": null
}
```

### Captured examples

Inbox routes: Postman `shared.notifications.index` › "200 Inbox with unread count", `shared.notifications.show` › "200 Open one notification and mark it read", `shared.notifications.destroy` › "200 Delete one notification", `shared.notifications.mark-all-read` › "200 Mark all as read", `shared.notifications.clear-all` › "200 Clear the inbox". The list shape is shown in [API_CONVENTIONS §7](../API_CONVENTIONS.md). A notification of another app answers 404 (Postman: `shared.notifications.show` › "404 Another app's notification").

### 3.1 Notification preferences (DEC-13, TD-166)

The server keeps one switch pair per category for **this app only**: `orders`, `payments`, `chat`, `offers`, `account`. Customer and provider settings of the same phone are separate. A category with no saved row reads as on. The read never creates rows.

`GET` response (Postman: `delivery.notifications.preferences.categories.show`):

```json
{
    "status": "success",
    "message": "Data retrieved successfully",
    "data": {
        "allow_notifications": true,
        "sms_delivery_available": false,
        "categories": [
            {
                "category": {
                    "value": "orders",
                    "label": "Orders and trips"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "payments",
                    "label": "Payments and payouts"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "chat",
                    "label": "Chat messages"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "offers",
                    "label": "Offers"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "account",
                    "label": "Account and support"
                },
                "push_enabled": true,
                "sms_enabled": true
            }
        ]
    }
}
```

`PUT` body: `{"categories": {"orders": {"push_enabled": false}, "chat": {"sms_enabled": false}}}`. Send at least one category; each category needs at least one of `push_enabled` / `sms_enabled` (booleans); an unknown category or field is a 422. Categories and fields you omit stay unchanged. The response is the full state (Postman: `delivery.notifications.preferences.categories.update` › "200 …"):

```json
{
    "status": "success",
    "message": "Preferences updated",
    "data": {
        "allow_notifications": true,
        "sms_delivery_available": false,
        "categories": [
            {
                "category": {
                    "value": "orders",
                    "label": "Orders and trips"
                },
                "push_enabled": false,
                "sms_enabled": false
            },
            {
                "category": {
                    "value": "payments",
                    "label": "Payments and payouts"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "chat",
                    "label": "Chat messages"
                },
                "push_enabled": true,
                "sms_enabled": false
            },
            {
                "category": {
                    "value": "offers",
                    "label": "Offers"
                },
                "push_enabled": true,
                "sms_enabled": true
            },
            {
                "category": {
                    "value": "account",
                    "label": "Account and support"
                },
                "push_enabled": true,
                "sms_enabled": true
            }
        ]
    }
}
```

Validation (Postman: `delivery.notifications.preferences.categories.update` › "422 Unknown category"):

```json
{
    "status": "fail",
    "message": "The categories field must be an array.",
    "data": {
        "errors": {
            "categories": [
                "The categories field must be an array."
            ]
        }
    }
}
```

Rules to know:
- **Master switch.** `allow_notifications` is account-wide. `PUT /api/v1/client/notifications/preferences` (unchanged) still sets it (the provider and driver apps have no route of their own for it; they only read it here); when it is `false`, no push reaches any of the person's apps whatever the categories say. When `true`, the category decides.
- **Only push is filtered.** The inbox row is always written and realtime events are unaffected. A muted category simply produces no FCM message.
- **Nothing is unmutable yet.** Whether some messages (for example account review results or payment failures) must always reach the user is an open owner decision (DEC-28); until then every category can be switched off.
- **SMS.** `sms_enabled` is stored for later. No SMS is sent today (provider open, DEC-15) and the response says `sms_delivery_available: false`; do not promise SMS in the UI.
- **OS permission.** Whether the phone allows this app to show notifications is an operating-system setting the server cannot see. Ask for it in the app and show your own hint when it is denied.
- **Event to category.** See the catalog in [API_CONVENTIONS §7.1](../API_CONVENTIONS.md).

## 4. Push delivery

Creating a persisted `Notification` dispatches `SendPushNotificationJob`. Delivery requires `FIREBASE_ENABLED=true`, valid Firebase credentials, the user's `allow_notifications` flag and the event's category switch for this app (§3.1). It targets devices registered for the notification's `driver` app. Invalid or unknown tokens are pruned. Per-token transient failures are not retried (TD-143).

The push includes a notification title and body, plus data containing the notification UUID (`notification_id`), the app (`app`), and any data stored on the notification.

## 5. Event catalog, device lifecycle and what is left

- Every event key this app can receive, its trigger, category and `data` keys: [API_CONVENTIONS §7.1](../API_CONVENTIONS.md). The push `data` does not carry the event key; route a tapped push by the `data` keys or by `notification_id`.
- Device-token behaviour (rotation, several devices, two apps on one phone, logout, invalid tokens, retries): [API_CONVENTIONS §7.2](../API_CONVENTIONS.md). Send `device_token` in the logout body so the token is detached.
- **Still open.** SMS delivery (DEC-15; SMS is only logged), WhatsApp (not integrated), promotions beyond the admin's `general` notification (the `offers` category holds only `general`), the owner's answers on DEC-28 and DEC-29, and a verified FCM delivery on staging (DevOps checklist in the handoff reply). Templates and the admin notification screens are built ([admin/notifications.md](../admin/notifications.md), TD-167).
