FCM API reference — BlueBubbles SDK

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

string

required

A human-readable name for the device being registered. This helps you identify registered devices in the server UI. Example: "pixel5a".

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.

​FCM client configuration

​getFcmClientConfig()

​Device registration

​registerDevice()

FCM client configuration

`getFcmClientConfig()`

Device registration

`registerDevice()`