[!WARNING] This library is based on reverse‑engineering legacy GCM/FCM protocols and is not actively maintained.
It is provided for reference/experimentation only and may stop working if Google/Firebase change their internals.

fcm-node-receiver

Repository: [email protected]:cuongdev/fcm-node-receiver.git

Goal: receive push notifications sent via Firebase Cloud Messaging (FCM) inside a Node.js process by emulating a device client and using the latest known FCM registration endpoints.

The original push-receiver FCM registration endpoint was deprecated and removed as of June 20, 2024.
This project uses the newer Firebase Installation + FCM registration APIs where possible, but still depends on undocumented behaviour which may break over time.

When should I use fcm-node-receiver?

• Receive push notifications in a Node.js process (e.g. for bots, bridges, or background workers).
• Communicate with a Node.js server through Firebase Cloud Messaging infrastructure.

When should I not use fcm-node-receiver?

• You only need to send notifications → use official Firebase Admin SDK / client SDKs instead.
• Your app runs on an officially supported FCM platform (Android, iOS, Web) → use the official clients instead of emulating a Node client.

Install

npm install --save fcm-node-receiver

Requirements

• Node v8+ (async/await support).
• Firebase apiKey, appID, and projectID to receive notifications.

Basic usage

const { register, listen } = require('fcm-node-receiver');

// Firebase config
const config = {
  firebase: {
    apiKey: 'XXxxXxX0x0x-Xxxx0-X0Xxxxx_0xxXx_XX0xXxX',
    appID: '1:000000000000:android:xxx0xxxx0000x000xxx000',
    projectID: 'the-app-name',
  },
  vapidKey: '', // optional
};

// First time
// Register to FCM and obtain credentials
const credentials = await register(config); // Call once and persist the credentials somewhere
storeCredentials(credentials);
const fcmToken = credentials.fcm.token; // Use this token to send notifications via FCM
sendTokenToBackendOrWhatever(fcmToken);

// Next times (reuse stored credentials)
const savedCredentials = getSavedCredentials(); // Load from file/db/...
// persistentIds is the list of notification ids received, to avoid replaying old notifications.
const persistentIds = getPersistentIds() || [];
await listen({ ...savedCredentials, persistentIds }, onNotification);

// Called on new notification
function onNotification({ notification, persistentId }) {
  // Persist the new persistentId
  updatePersistentIds([...persistentIds, persistentId]);
  // Handle the notification payload
  display(notification);
}

Test notification (HTTP v1)

To test, you can use the scripts/send/index.js script in this repo, which uses the FCM HTTP v1 send endpoint. You need a Firebase service account JSON file and the FCM registration token as arguments:

node scripts/send \
  --serviceAccountPath="/path/to/serviceAccount.json" \
  --token="<FCM_TOKEN>" \
  --projectId="<FIREBASE_PROJECT_ID>"

The projectId argument is optional if project_id is present in the service account JSON.

Acknowledgements

• push-receiver for the original implementation.
• Aracna FCM for the latest FCM registration endpoints.