Skip to main content

Sending Push Notifications

Push notifications are always triggered from a secure server environment using the Admin SDK. EdgeBase routes all payloads through FCM HTTP v1 API to reach devices across all platforms.

Language Coverage

Push sending is available in all Admin SDKs.

Setup​

Initialize the Admin SDK with your Service Key.

import { createAdminClient } from '@edgebase/admin';

const admin = createAdminClient('https://my-edgebase-server.com', {
    serviceKey: process.env.EDGEBASE_SERVICE_KEY
});

Sending to a User​

Send a push notification to all devices registered to a specific user.

const result = await admin.push.send("user_123", {
    title: "New Message",
    body: "Alice sent you a photo!",
    badge: 1
});
console.log(result); // { sent: 2, failed: 0, removed: 0 }

Response Object​

All send methods return a summary:

  • sent — Devices that successfully received the notification.
  • failed — Devices that failed (network errors, bad config).
  • removed — Devices whose tokens were automatically cleaned up (e.g., app uninstalled).

Sending to Multiple Users (Bulk)​

Send to multiple users in one call. The server automatically chunks requests into parallel batches.

const result = await admin.push.sendMany(["user_1", "user_2", "user_3"], {
    title: "Server Maintenance",
    body: "We will be down for 5 minutes."
});

Sending to a Raw FCM Token​

Send directly to any FCM token without looking up registered users. Useful for testing, external integrations, or when you manage tokens outside EdgeBase.

const result = await admin.push.sendToToken("fcm-token-abc123...", {
    title: "Silent Sync",
    silent: true
});

Sending to a Topic​

Send a push notification to all devices subscribed to a specific topic. Devices subscribe to topics via the client SDK (client.push.subscribeTopic('news')).

const result = await admin.push.sendToTopic("news", {
    title: "Breaking News",
    body: "Something important happened!"
});

Broadcasting to All Devices​

Send a push notification to every registered device. This uses the special all topic that all devices are automatically subscribed to on registration.

const result = await admin.push.broadcast({
    title: "App Update",
    body: "Version 2.0 is now available!"
});

Push Payload​

interface PushPayload {
  title?: string;                   // Notification title
  body?: string;                    // Notification body text
  image?: string;                   // Image URL (Android/Web)
  sound?: string;                   // Sound file name
  badge?: number;                   // Badge count (iOS)
  data?: Record<string, unknown>;   // Custom key-value pairs
  silent?: boolean;                 // true = background data push (no alert)
  collapseId?: string;              // Overwrite previous unread notifications
  ttl?: number;                     // Seconds before expiring (0 = deliver now or drop)
  fcm?: Record<string, unknown>;    // FCM-specific raw overrides
}

[!TIP] Silent Pushes: Set silent: true to deliver a background data-only notification. The device won't show an alert, play a sound, or update the badge. Use this for background data sync.

Reading Push Logs​

Query push send logs for debugging. Logs are retained for 24 hours.

const logs = await admin.push.getLogs("user_123", 10);
console.log(logs);

Each log entry contains:

  • sentAt — Timestamp
  • userId — Target user
  • platform — Device platform
  • status — 'sent', 'failed', or 'removed'
  • error — Error message (if failed)
  • collapseId — Collapse key (if set)