Skip to main content
Firebase Cloud Messaging (FCM) is the push notification system BlueBubbles uses to wake up client apps when new iMessages arrive. Instead of keeping a persistent connection open, the server sends an FCM push notification to your registered device, which then fetches the new data over the REST API. The FCM service in the SDK gives you two operations: fetching the server’s FCM client configuration (needed to initialize Firebase on the client side) and registering a device to receive those notifications. Access the service through client.fcm.
To use FCM with the BlueBubbles Server, you must have Firebase configured on your server. Follow the BlueBubbles Server setup guide to upload your FCM credentials before calling these endpoints.

​
FCM client configuration

​
getFcmClientConfig()

Returns the FCM client configuration from your BlueBubbles Server. Use this configuration to initialize the Firebase SDK on your client application so it can register for push notifications through the correct Firebase project. Signature 
client.fcm.getFcmClientConfig(): CancelablePromise<any>
Example 
const config = await client.fcm.getFcmClientConfig();

// Use the returned config to initialize Firebase on your client
// e.g., initializeApp(config.data) in a React Native or web app
console.log(config.data);
Fetch the FCM client config once at app startup and cache it. The configuration only changes when the server administrator rotates the Firebase credentials.

​
Device registration

​
registerDevice()

Registers a device with the BlueBubbles Server so it can receive FCM push notifications. You generate the FCM identifier (also called a registration token) by authenticating with Google Firebase on the client side, then pass it to this endpoint so the server knows where to send notifications. Signature 
client.fcm.registerDevice({
  requestBody,
}: {
  requestBody?: Record<string, any>;
}): CancelablePromise<any>
Request body parameters
​
name
string
required
A human-readable name for the device being registered. This helps you identify registered devices in the server UI. Example: "pixel5a".
​
identifier
string
required
The FCM registration token generated when your client app authenticates with Google Firebase. The server uses this token to route push notifications to your specific device.
Example 
// After authenticating with Firebase on the client and obtaining a token:
const fcmToken = await getFCMToken(); // your Firebase client call

await client.fcm.registerDevice({
  requestBody: {
    name: "pixel5a",
    identifier: fcmToken,
  },
});

// Re-register when the FCM token is refreshed by Firebase
messaging().onTokenRefresh(async (newToken) => {
  await client.fcm.registerDevice({
    requestBody: {
      name: deviceName,
      identifier: newToken,
    },
  });
});
FCM registration tokens expire and are rotated by Google Firebase. Listen for token refresh events in your Firebase client and call registerDevice() again with the new token to avoid missing notifications.