Cloud Messaging

How it works

1. Your app obtains an FCM token using firebase_messaging
2. The SDK registers the token with Koolbase — tied to a stable device ID, using the publishable key
3. Your backend (or a Koolbase Function, or the dashboard broadcast UI) sends with a secret API key
4. Koolbase authenticates to FCM's HTTP v1 API and delivers to Android and iOS

Setup

Delivery goes through FCM's HTTP v1 API, which authenticates with short-lived OAuth tokens minted from a Firebase service account. Koolbase handles the minting and caching; you provide the service account once.

1. Firebase Console → your project → ⚙️ Project settings → Service accounts → Generate new private key. A JSON file downloads.
2. Koolbase dashboard → your project → Secrets → create a secret named exactly FCM_SERVICE_ACCOUNT.
3. Paste the entire JSON file as the value — from the opening { to the closing }, unmodified. Don't extract fields, don't strip the \ns inside the private key.

Flutter SDK — register devices

Install firebase_messaging, then register the FCM token after initialization. Pass the signed-in user's id to target notifications per user later. Messaging is on by default; setting messagingEnabled: false in KoolbaseConfig disables the client entirely.

// After Firebase is initialized
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
  await Koolbase.messaging.registerToken(
    token: fcmToken,
    platform: 'android', // or 'ios'
    userId: currentUser?.id,
  );
}

// Tokens rotate — keep the registration fresh:
FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  Koolbase.messaging.registerToken(token: newToken, platform: 'android');
});

Registration is idempotent per device: re-registering updates the stored token rather than duplicating it.

React Native SDK — register devices

import messaging from '@react-native-firebase/messaging';

const fcmToken = await messaging().getToken();
await Koolbase.messaging.registerToken({
  token: fcmToken,
  platform: 'android', // or 'ios'
});

messaging().onTokenRefresh(async (newToken) => {
  await Koolbase.messaging.registerToken({
    token: newToken,
    platform: 'android',
  });
});

Send from your backend

Sends are a single POST with a secret key. project_id is required in the body — keys are organization-scoped, and the project must belong to the key's organization.

curl -X POST https://api.koolbase.com/v1/messaging/send \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer kb_live_..." \
            --data '{
              "project_id": "your-project-id",
              "token": "the-device-fcm-token",
              "title": "Order shipped",
              "body": "Your order #1042 is on its way",
              "data": { "order_id": "1042" }
            }'

To notify a user rather than a specific device, send user_id instead of token (exactly one is required). Koolbase resolves all of that user's registered devices, sends to each, and prunes dead tokens — so your backend or Function never handles raw device tokens:

curl -X POST https://api.koolbase.com/v1/messaging/send \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer kb_live_..." \
              --data '{
                "project_id": "your-project-id",
                "user_id": "the-project-user-id",
                "title": "Order shipped",
                "body": "Your order #1042 is on its way"
              }'
            # Response: { "sent": 1, "failed": 0, "pruned": 0, "devices": 1 }

The recommended pattern for app-driven notifications is a Koolbase Function: a database trigger or invoked Function runs server-side with access to your secrets, so it can send without any credential ever reaching the client.

Responses and errors

Dashboard broadcast

Send to all registered devices from the dashboard: project → Messaging → title, body, optional data → Broadcast. Broadcast authenticates with your dashboard session, not an API key.

• Total registered devices — Android and iOS count
• Sent today / Failed today — delivery stats
• Recent sends log — status per message
• Broadcast to all — one-click send to every registered token, with pruned count

What Koolbase does not handle

• Receiving messages in the app — use firebase_messaging for that
• Notification permissions — request via the platform SDK
• Background message handlers — configure in firebase_messaging
• Web push notifications — mobile only in v1

API reference