Notifications

Overview

MechZie uses Firebase Cloud Messaging (FCM) for push notifications with Fast2SMS as an SMS fallback. All notifications are also stored in-app for retrieval via the API.

Setting Up Push Notifications

Register FCM Token

On app startup and whenever the FCM token refreshes, register it with the API:

final fcmToken = await FirebaseMessaging.instance.getToken();

await http.put(
  Uri.parse('$baseUrl/api/v1/notifications/fcm-token'),
  headers: {
    'Authorization': 'Bearer $accessToken',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'token': fcmToken,
    'device_info': 'Flutter Android 14',  // optional
  }),
);

curl -X PUT https://mechzie-api-production.run.app/api/v1/notifications/fcm-token \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "fcm-device-token-string",
    "device_info": "Flutter Android 14"
  }'

Call this on every app launch. The server tracks last_used_at and automatically prunes stale tokens. If you don’t re-register, the token may be cleaned up and the user will stop receiving push notifications.

Listen for Token Refresh

FirebaseMessaging.instance.onTokenRefresh.listen((newToken) async {
  await registerFcmToken(newToken);
});

Listing Notifications

Fetch in-app notifications (paginated):

GET /api/v1/notifications?page=1&limit=20
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "title": "Mechanic on the way",
      "body": "Ravi is heading to your location. ETA: 8 minutes.",
      "data": {
        "jobId": "uuid",
        "type": "job_status_change",
        "status": "en_route"
      },
      "is_read": false,
      "created_at": "2026-05-21T10:30:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 15
}

Marking as Read

Mark a single notification

PATCH /api/v1/notifications/{id}/read
Authorization: Bearer ACCESS_TOKEN

Mark all as read

PATCH /api/v1/notifications/read-all
Authorization: Bearer ACCESS_TOKEN

Notification Triggers

These events generate notifications for the relevant user:

Customer Notifications

Trigger	Title Example	When
Mechanic accepted job	”Mechanic assigned”	Job status → `accepted`
Mechanic en route	”Mechanic on the way”	Job status → `en_route`
Mechanic arrived	”Mechanic has arrived”	Job status → `arrived`
Job completed	”Service completed”	Job status → `completed`
Payment failed	”Payment failed”	Razorpay `payment.failed` webhook
Refund processed	”Refund issued”	Admin initiates refund (FCM + email)
No mechanic found	”No mechanics available”	All dispatch tiers exhausted
Chat message	”Message from Ravi”	Other participant sends chat while app is backgrounded
Missed call	”Missed call from Ravi”	In-app call timed out or was declined

Mechanic Notifications

Trigger	Title Example	When
New job offer	”New job nearby”	Dispatch sends `job:offer`
Job cancelled by customer	”Job cancelled”	Customer cancels
Verification approved	”Profile verified”	Admin approves mechanic
Verification rejected	”Verification update”	Admin rejects mechanic
Document review	”Document reviewed”	Admin approves/rejects document
Chat message	”Message from Priya”	Customer sends chat while app is backgrounded
Missed call	”Missed call from Priya”	In-app call timed out or was declined

Notification Data Payload

The data field contains structured data for deep-linking. Use it to navigate the user to the relevant screen:

FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
  final data = message.data;

  switch (data['type']) {
    case 'job_status_change':
      navigateToJob(data['jobId']);
      break;
    case 'job_offer':
      navigateToJobOffer(data['jobId']);
      break;
    case 'payment_failed':
      navigateToPayment(data['jobId']);
      break;
    case 'mechanic_verified':
      navigateToProfile();
      break;
    case 'refund_processed':
      navigateToPaymentHistory(data['jobId']);
      break;
    case 'chat_message':
      navigateToChat(data['jobId']);
      break;
    case 'call_missed':
      navigateToJob(data['jobId']);
      break;
  }
});

Delivery Channels

Channel	Priority	Notes
FCM Push	Primary	Requires registered token. Job-offer pushes use high-priority payloads to wake devices instantly.
Fast2SMS	Fallback	Used when FCM delivery fails (fallback is skipped for job offers).
Email (Resend)	Specific events	Admin invites, refund confirmations
Socket.io	Real-time	`job:status`, `payment:failed`, etc. (see Real-time Events)
In-App	Persistent	Always stored in `notifications` table

Reliable Push Delivery (Inline-first with Fallback)

To ensure mechanics receive job offers instantly without delay, the API uses a two-stage delivery mechanism:

Inline Send (Stage 1): When a job is dispatched, the API attempts to send the FCM push notification inline with a strict 1-second timeout. If Firebase accepts the message within this window, the delivery is complete.
Queue Fallback (Stage 2): If the inline send times out or fails, a BullMQ job is enqueued immediately. The background worker attempts to reclaim and deliver the notification. It retries up to 3 times using exponential backoff (retry 1 at +2s, retry 2 at +4s).

FCM Payload Priority

For critical notifications (like job_offer):

Android: Priority is set to high with a TTL of 30 seconds.
iOS (APNs): apns-priority is set to 10 with expiration set to 30 seconds.
Background Prefetching: APNs payload includes content-available: 1 to allow background state updates/pre-fetching of job data before the user taps the alert.

Push notifications and Socket.io events often carry the same information. Socket.io is for real-time UI updates while the user is active. Push notifications reach users when the app is in the background. In-app notifications serve as a persistent history.

Unread Badge Count

The API doesn’t have a dedicated unread count endpoint, but you can calculate it from the notification list:

final response = await api.get('/notifications?page=1&limit=1');
// Use the total count of unread notifications
// Or filter client-side: data.where((n) => !n.is_read).length

For a proper unread count, fetch the first page and count items where is_read == false. Consider caching this and updating it when you mark notifications as read.

Getting Started

Guides

Development

Overview

Setting Up Push Notifications

Register FCM Token

Listen for Token Refresh

Listing Notifications

Marking as Read

Mark a single notification

Mark all as read

Notification Triggers

Customer Notifications

Mechanic Notifications

Notification Data Payload

Delivery Channels

Reliable Push Delivery (Inline-first with Fallback)

FCM Payload Priority

Unread Badge Count

​Overview

​Setting Up Push Notifications

​Register FCM Token

​Listen for Token Refresh

​Listing Notifications

​Marking as Read

​Mark a single notification

​Mark all as read

​Notification Triggers

​Customer Notifications

​Mechanic Notifications

​Notification Data Payload

​Delivery Channels

​Reliable Push Delivery (Inline-first with Fallback)

​FCM Payload Priority

​Unread Badge Count

Overview

Setting Up Push Notifications

Register FCM Token

Listen for Token Refresh

Listing Notifications

Marking as Read

Mark a single notification

Mark all as read

Notification Triggers

Customer Notifications

Mechanic Notifications

Notification Data Payload

Delivery Channels

Reliable Push Delivery (Inline-first with Fallback)

FCM Payload Priority

Unread Badge Count