Push Notifications

Send push notifications to your users’ registered devices from your backend

The push module lets your backend fan a notification out to every registered device belonging to one or more users — across iOS (APNs), Android (FCM), and Web Push — in a single call.

Requires the push bundle and configured provider credentials (APNs, FCM, or Web Push) in the project dashboard. See Push Notifications for the full setup guide.

---

send

Sends a push notification to all registered devices for the given user IDs. Dispatches to APNs, FCM, and Web Push in parallel.

const result = await sublay.push.send({
  userIds: ["usr_abc123", "usr_def456"],
  title: "New message",
  body: "You have a new message from Alice.",
  data: { conversationId: "conv_xyz789" },
  sound: "notification.wav",
  channelId: "messages",
  badge: 3,
  tag: "conv_xyz789",
});

userIds · string[] · required

Sublay user IDs to notify. Maximum 100 per call.

title · string · required

Notification title shown on the device.

body · string · required

Notification body text.

data · Record<string, any>

Optional key-value payload forwarded to the app alongside the notification. Use for deep links, entity IDs, or any context your app needs when the user taps.

Rich payload fields

All optional. Each maps to whichever platform(s) support it and is silently ignored elsewhere (e.g. subtitle/threadId are iOS-only, channelId is Android-only). See Rich notification payloads for the platform setup each one needs.

sound · string

Sound file to play. iOS: APNs sound. Android: on 8+ the sound is owned by the notification channel — pair this with channelId and create that channel client-side with the sound set. Web: forwarded to your service worker.

badge · number

iOS app-icon badge count (APNs badge). No Android equivalent. Your backend supplies the number — Sublay does not track per-user unread counts.

channelId · string

Android notification channel id (FCM). The channel must be created client-side; on Android 8+ it governs sound, importance, and vibration.

priority · "high" | "normal"

Delivery priority. high wakes the device for time-sensitive pushes; normal is power-considerate. Maps to APNs apns-priority and FCM android.priority.

subtitle · string

iOS subtitle line shown under the title (APNs alert.subtitle).

imageUrl · string

Rich/big-picture image URL. Works out of the box on Android (FCM) and Web. On iOS it additionally requires a Notification Service Extension in your app; the URL is forwarded in the payload and mutable-content is set automatically.

tag · string

Display-replace key so notifications collapse in the UI instead of stacking (FCM android.notification.tag, Web tag). Use a per-conversation value to keep one entry per thread.

collapseId · string

Transport-level collapse identifier (APNs apns-collapse-id, FCM collapse_key) — a newer push supersedes an undelivered one with the same id.

threadId · string

iOS notification grouping (APNs thread-id).

ttl · number

Time-to-live in seconds for offline devices (APNs apns-expiration, FCM android.ttl). After this window the provider stops retrying.

mutableContent · boolean

iOS mutable-content flag, letting your Notification Service Extension modify the payload (e.g. attach imageUrl). Set implicitly when imageUrl is provided.

Returns — Promise<SendPushResult>

interface SendPushResult {
  results: Record<string, PushDeviceResult[]>;
}

interface PushDeviceResult {
  platform: string;   // "ios" | "android" | "web"
  success: boolean;
  reason?: string;    // present when success is false
}

Every requested userId is present in results — users with no registered devices get an empty array. Stale device tokens that are permanently rejected by the upstream provider are automatically removed; you don’t need a separate cleanup step.

Example response:

{
  "results": {
    "usr_abc123": [
      { "platform": "ios", "success": true },
      { "platform": "web", "success": true }
    ],
    "usr_def456": [],
    "usr_ghi789": [
      { "platform": "android", "success": false, "reason": "credentials_not_configured" }
    ]
  }
}

Common reason values when success is false:

Reason	Meaning
credentials_not_configured	No provider credentials are configured (or enabled) for this platform
Provider error codes	APNs, FCM, or Web Push returned a delivery error