Skip to main content
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 (the default when omitted) 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:
ReasonMeaning
credentials_not_configuredNo provider credentials are configured (or enabled) for this platform
Provider error codesAPNs, FCM, or Web Push returned a delivery error

​
Notification preferences

Read and update a user’s per-type push preferences — the set of event types they’ve disabled for push. See Notification Preferences & Mute for the model and the full event palette.
These endpoints are per-user. The Node SDK authenticates with a service key, so — exactly like the other per-user operations — you name the user with an explicit userId and the SDK acts on that user’s behalf. (End-user-token clients, such as the React hooks and the browser JS SDK, act on the signed-in user and omit userId.)

​
getNotificationPreferences

Reads a user’s disabled push types. Returns an empty array (all-on) when no preferences are set. 
const { disabledTypes } = await sublay.push.getNotificationPreferences({
  userId: "usr_abc123",
});
​
userId
string
required
The user whose preferences to read.
Returns — Promise<NotificationPreferences> 
interface NotificationPreferences {
  disabledTypes: PushEventType[]; // e.g. ["new-follow", "message"]
}

​
updateNotificationPreferences

Replaces a user’s disabled-types set (upsert). Send the complete set you want stored, not a delta; only valid event type names are accepted. 
import { PUSH_EVENT_TYPES } from "@sublay/node";

await sublay.push.updateNotificationPreferences({
  disabledTypes: ["comment-mention", "message"],
  userId: "usr_abc123",
});
​
disabledTypes
PushEventType[]
required
The complete set of event types to disable for push. Values must be from PUSH_EVENT_TYPES (see the event palette); unknown names are rejected. Pass [] to re-enable everything.
​
userId
string
required
The user whose preferences to write.
Returns — Promise<NotificationPreferences> (the stored, deduplicated set).

​
Conversation mute

Setting or clearing a conversation mute lives on the chat module (it’s a /chat/... route): chat.muteConversation. Like the preference endpoints it is per-user — name the acting user with userId — and takes a duration choice, never a timestamp.