Firebase Cloud Messaging (FCM)

Firebase Cloud Messaging is a free notification delivery service provided by Google Firebase.

To enable the FCM integration, you need to get your service account key from the Firebase Console.

Generating a service account key JSON

To acquire the account key JSON file for your service account

1. Select your project, and click the gear icon on the top of the sidebar.
2. Head to project settings.
3. Navigate to the service account tab.
4. Click Generate New Private Key, then confirm by clicking Generate Key.
5. Clicking Generate Key downloads the JSON file.

After that, paste the entire JSON file content in the Service Account field of the FCM provider in the integration store on Novu's web dashboard.

Make sure your service account json content contains these fields

{
  "type": "service_account",
  "project_id": "PROJECT_ID",
  "private_key_id": "PRIVATE_KEY_ID",
  "private_key": "PRIVATE_KEY",
  "client_email": "FIREBASE_ADMIN_SDK_EMAIL",
  "client_id": "CLIENT_ID",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "CLIENT_X509_CERT_URL"
}

FCM overrides

The overrides field supports apns, android, webpush and fcmOptions overrides

Managing device tokens

Before triggering the notification to a subscriber(user) with push as a step in the workflow, make sure you have added the subscriber's device token as follows:

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.Fcm,
    credentials: {
      deviceTokens: ["token1", "token2", "token3"],
    },
  },
  "subscriberId"
);

Checkout the API reference for more details.

Managing device tokens for multiple integrations

Novu supports multiple active integrations per provider for push channel. There can be more than one FCM integration active at a time. By default, device tokens are stored for recently created integration. To store device tokens for a specific integration, you can use the integrationIdentifier field. integrationIdentifier is the identifier of the integration in the Novu dashboard.

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.Fcm,
    // Use integrationIdentifier to store device tokens for a specific integration
    integrationIdentifier: "fcm-MnGLxp8uy",
    credentials: {
      deviceTokens: ["token1", "token2", "token3"],
    },
  },
  "subscriberId"
);

SDK trigger example

By default, Novu will send the FCM notification content written in the step editor workflow. You can override the notification content by using the overrides field. Use type: data and data to send data type notification.

import { Novu } from '@novu/api';
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    providers: {
      fcm: {
        type: "data",
 
        // URL of an image to be displayed in the notification.
        imageUrl: "https://domain.com/image.png",
 
        // If type is not set, you can use the "data" override to send notification messages with optional data payload
        data: {
          key: "value",
        },
 
        // Check FCM Overrides section above for these types
        android: {},
        apns: {},
        webPush: {},
        fcmOptions: {},
      },
    },
  },
});

Relative link in webpush

Suppose you're using the Firebase (FCM) provider to send push notifications to web browsers via Novu and want users to be returned to the website after clicking the notification.

In that case, you must use the link property with a relative URL.

import { Novu } from '@novu/api';
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    providers: {
      fcm: {
        webPush: {
          fcmOptions: {
            link: "/foo",
          },
        },
      },
    },
  },
});

Sending notifications to FCM topics

FCM topics are used to send notifications to multiple devices at once. Use trigger overrides to send notifications to a topic. In this case, subscriber device tokens are not required.

import { Novu } from '@novu/api';
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    providers: {
      fcm: {
        topic: "topic-123",
      },
    },
  },
});

FCM cost

As per Firebase pricing, Cloud Messaging product is free of cost to use. If other Firebase products are used, the cost will be charged as per the product.

Frequently asked questions

While using the FCM provider, you may encounter the following issues.

The registration token is not a valid FCM registration token

You may come across an error like so:

Sending message failed due to "The registration token is not a valid FCM registration token"

This error happens because of invalid or stale token. The fix for this is to remove old tokens, generate a new token and save it into user subscribers.

FCM notifications sent successfully with no error but push notification is not received in device

Try to generate a new token after clearing device cache and retry with this fresh token.

Sending message failed due to 'Requested entity was not found'

This error occurs when your token is no longer valid. To fix this, generate a new token and use it.

Subscriber does not have a configured channel error

This error occurs if the fcm integration is active but subscriber is missing from the fcm credentials (deviceTokens). The credentials (deviceTokens) for the subscriber needs to be set.

How to send desktop notifications using FCM

Desktop notifications for websites can be sent using FCM webpush.