> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Requires the `push` bundle and configured provider credentials (APNs, FCM, or Web Push) in the project dashboard. See [Push Notifications](https://docs.sublay.io/v7/push-notifications.md) 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.

```typescript theme={null}
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.

**`recipientUserId` is reserved.** Sublay stamps every dispatched copy with the id of the account it is for, so a device signed into several accounts can tell which one a notification belongs to. A value you set under that key is overwritten — an account-routing key has to be trustworthy.

> [!NOTE]
>
> **One notification per account, not per device.** A physical device can be bound to several accounts at once. If two of the `userIds` are signed in on the same device, that device receives two notifications — one per account, each carrying its own `recipientUserId`.

#### 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](https://docs.sublay.io/v7/push-notifications.md#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](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) 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. Scoped per recipient, like `collapseId` below.

**collapseId** `string`

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

Both keys are scoped to the recipient before they reach the provider: two accounts signed in on one physical device share a single transport destination, so the server appends a short digest of the recipient's id and each account collapses only against itself. That means the device receives a different string than you sent — client code reading the delivered `tag` must match on a prefix rather than on equality, or carry its own key in `data`, which is passed through untouched. An over-length `collapseId` is folded into a fixed-width digest rather than refused by APNs — see [the endpoint reference](https://docs.sublay.io/v7/api-reference/push-notifications/send.md).

**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>`

```typescript theme={null}
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. Device tokens permanently rejected by the upstream provider are automatically removed; you don't need a separate cleanup step. A dead token is dead for the whole device, so removal unbinds **every** account registered on it, including accounts outside this call.

**Example response:**

```json theme={null}
{
  "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 |

***

## 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](https://docs.sublay.io/v7/notification-preferences.md) for the model and the full event palette.

> [!NOTE]
>
> 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.

```typescript theme={null}
const { disabledTypes } = await sublay.push.getNotificationPreferences({
  userId: "usr_abc123",
});
```

**userId** `string` *required*

The user whose preferences to read.

**Returns** — `Promise<NotificationPreferences>`

```typescript theme={null}
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.

```typescript theme={null}
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](https://docs.sublay.io/v7/notification-preferences.md#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`](https://docs.sublay.io/v7/node-sdk/chat#muteconversation). Like the preference endpoints it is per-user — name the acting user with `userId` — and takes a duration **choice**, never a timestamp.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.