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

# Notifications & Engagement

> Build a notification inbox with seen/unseen state, real-time delivery, push notification setup, and granular event-based triggers.

> [!NOTE]
>
> **SDK v7.x** · Last verified March 2026 · iOS · Android · Web · Flutter

> **Speed run — just the code**
>
> > [!WARNING]
> >
> > **TypeScript SDK gap**: `Client.registerPushNotification` is not available in the TypeScript SDK. iOS and Android use native push token registration. In TS/Web, configure push notifications via your web push service (e.g., Firebase Messaging). Tracking: see `.docs-ops/evals/sdk-tickets-to-file.md`.
>
> ```typescript theme={null}
> // 1. Get notification tray items
> const { data } = await notificationTray.getNotificationTrayItems({ limit: 20 });
>
> // 2. Mark a notification as seen
> await notificationTray.markTraySeen('notificationId');
>
> // 3. Register push token
> // Push token registration not in TS SDK (see Warning above)
> // Configure push via your web push service (e.g., Firebase Messaging)
> });
>
> // 4. Subscribe to real-time tray updates
> notificationTray.onNotificationTraySeenUpdated(({ data }) => {
>   showBadge(data.unseenCount);
> });
> ```
>
> Full walkthrough below ↓

> [!TIP]
>
> **Platform note** — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.

Notifications are your primary re-engagement tool. This guide covers building an in-app notification tray with seen/unseen tracking, setting up push notifications across all platforms, and subscribing to real-time social events.

```mermaid theme={null}
graph TD
    A[Social activity occurs] --> B{Who triggered it?}
    B -->|Comment on post| C[Post author notified]
    B -->|Reaction on content| D[Content author notified]
    B -->|Mention in comment| E[Mentioned user notified]
    B -->|New follower| F[Followed user notified]
    B -->|Community post| G[Community member notified]
    C & D & E & F & G --> H{Delivery channel}
    H -->|In-app open| I[Notification tray item]
    H -->|App backgrounded| J[Push notification]
    I --> K[User taps → navigates to content]
    J --> K

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,H decision
    class C,D,E,F,G,I,J process
    class K outcome
```

> [!NOTE]
>
> **Prerequisites**: SDK installed and authenticated. For push notifications: APNs certificate (iOS) or FCM credentials (Android) configured in **Admin Console → Settings → Integrations**.
>
> **Also recommended:** Complete [Build a Social Feed](/use-cases/social/build-a-social-feed.md) and [Community Platform](/use-cases/social/community-platform.md) first — notifications are triggered by feed and community events.

> [!NOTE]
>
> **After completing this guide you'll have:**
>
> * An in-app notification tray with seen/unseen state and real-time delivery
> * Push notifications (APNs and FCM) registered and firing for key events
> * Notification triggers mapped to SDK events and webhook callbacks

***

## Quick Start: Query Notification Tray

```typescript TypeScript theme={null}
import { notificationTray } from '@amityco/ts-sdk';

const unsubscribe = notificationTray.getNotificationTrayItems(
  { limit: 20 },
  ({ data: items, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(items);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);

unsubscribe();
```

***

## Part 1: In-App Notification Tray

**1. Get unseen notification count**

Use the tray status to show a badge count on your notification icon. The `unseenCount` updates in real-time.

```typescript theme={null}
import { notificationTray } from '@amityco/ts-sdk';

const unsubscribe = await notificationTray.getNotificationTraySeen(
  ({ data: notificationTraySeen, loading }) => {
    if (!loading && notificationTraySeen) {
      updateBadge(notificationTraySeen.unseenCount);
    }
  },
);
```

Full reference → [Notification Tray Status](/social-plus-sdk/social/discovery-engagement/notifications/notification-tray-status.md)

**2. Mark notifications as seen**

When the user opens the tray, mark all unseen items as seen. Or mark individual items as seen on tap. Both bulk and per-item marking are supported.

```typescript theme={null}
import { notificationTray } from '@amityco/ts-sdk';

// Mark all as seen
await notificationTray.markTraySeen();

// Or mark a single item
await item.markSeen();
```

Full reference → [Notification Tray Status](/social-plus-sdk/social/discovery-engagement/notifications/notification-tray-status.md)

**3. Navigate from a notification tap**

Each notification item contains `targetType` and `targetId` fields you can use to deep-link to the source content (post, comment, user, or community).

Reference all notification types → [Notification Events Reference](/social-plus-sdk/social/discovery-engagement/notifications/notification-events-reference.md)

***

## Part 2: Push Notifications

```mermaid theme={null}
sequenceDiagram
    participant Device as User's Device
    participant SDK
    participant Server as social.plus Server
    participant APNs as APNs / FCM

    Device->>SDK: registerPushNotification(token)
    SDK->>Server: Register device token
    Server-->>SDK: Registered

    Note over Server: Another user comments on the post
    Server->>Server: Generate notification
    alt App in foreground
        Server->>SDK: Real-time event
        SDK->>Device: In-app notification tray item
    else App in background
        Server->>APNs: Push payload
        APNs->>Device: System push notification
        Device->>SDK: User taps → deep link to content
    end
```

**1. Configure push credentials in Admin Console**

Before registering devices, add your push credentials in **Admin Console → Settings → Push Notifications**:

* **iOS**: Upload your APNs certificate or key
* **Android**: Add your FCM Server Key
* **React Native / Flutter**: Configure per platform

→ Platform setup guides: [iOS](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/ios-setup.md) · [Android](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/android-setup.md) · [React Native](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/react-native-setup.md) · [Flutter](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/flutter-setup.md)

**2. Register the device for push**

After the user logs in, retrieve the device token and register it with the SDK. This associates the device with the authenticated user so the backend can route pushes correctly.

```typescript theme={null}
import { Client } from '@amityco/ts-sdk';

// Register a device token (web push or React Native FCM token)
await client.registerPushNotification({ token: deviceToken });
```

Full reference → [Register Push Notifications](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device.md)

**3. Unregister on logout**

Always unregister the device token when the user logs out to prevent push notifications being sent to the wrong user's device.

```typescript theme={null}
// Unregister on logout — stops push notifications to this device
await client.unregisterPushNotification({ token: deviceToken });
```

Full reference → [Register Push Notifications](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device.md)

***

## Part 3: User Notification Preferences

Let users control what they're notified about at a granular level. Settings are organised by module (`SOCIAL`, `CHAT`, `LIVE_STREAM`) and apply across all of the user's devices.

**1. Get current notification settings**

Read the user's current preferences to populate a settings screen.

```typescript theme={null}
import { UserRepository } from '@amityco/ts-sdk';

// Notification settings API: see push-notification docs for v6 SDK approach
console.log('Notifications enabled:', settings.isEnabled);
settings.modules.forEach(m => console.log(m.moduleType, m.isEnabled));
```

**2. Update notification module settings**

Enable or disable individual modules, or turn off all notifications at once.

```typescript theme={null}
import { UserRepository } from '@amityco/ts-sdk';

// Disable social, keep chat enabled
// Notification settings update: see push-notification docs for v6 SDK approach
// await legacySettingsUpdate({
  modules: [
    { moduleType: 'social', isEnabled: false },
    { moduleType: 'chat',   isEnabled: true },
  ],
});

// Or disable all notifications at once
// Notification settings update: see push-notification docs for v6 SDK approach
// await legacySettingsUpdate({ isEnabled: false });
```

Full reference → [User Notification Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/user-settings.md)

**3. Configure community-level settings (optional)**

For finer control, users can configure which notification types they receive per community (new post, new comment, mentions). This is separate from the global user setting above.

Full reference → [Community Notification Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/community-settings.md)

***

## Connect to Moderation & Analytics

![Admin Console — Push notification settings](https://mintcdn.com/social-b97141fb-feat-user-history-moderation-detail/EuQgtDswnsuEu3tu/images/console-push-notifications-overview.png?fit=max\&auto=format\&n=EuQgtDswnsuEu3tu\&q=85\&s=a6aeec3efda983ec5bf246e96196dd5e)

Admin Console — Push notification settings for community and chat events

> **Webhook: trigger notifications for moderation actions**
>
> When a moderator removes content, use webhook events (`post.deleted`, `user.banned`) to send a custom in-app or push notification explaining the action to the affected user.
>
> → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event.md)

> **Notification analytics**
>
> Track notification open rates and click-through rates in **Admin Console → Analytics Dashboard → Engagement Metrics** to understand which notification types drive the most re-engagement.

***

## Common Mistakes

> [!WARNING]
>
> **Polling for notifications on a timer** — This drains battery and creates unnecessary API calls. Use real-time tray subscriptions instead:
>
> ```typescript theme={null}
> // ❌ Bad — polling every 5 seconds
> setInterval(() => fetchNotifications(), 5000);
>
> // ✅ Good — real-time tray subscription
> notificationTray.onNotificationTraySeenUpdated(({ data }) => {
>   updateBadge(data.unseenCount);
> });
> ```

> [!WARNING]
>
> **Not handling push permission rejection** — On iOS, users can deny push permissions. Always check the permission status and provide an in-app fallback (notification tray) when push is disabled.

> [!WARNING]
>
> **Registering push tokens before login** — Push token registration requires an active session. Always call `registerPushNotification` after `login()` completes, not in parallel.

## Best Practices

> **Notification tray UX**
>
> * Group related notifications (e.g., "5 reactions on your post") instead of showing individual items
> * Show a relative timestamp ("2 min ago") that updates while the tray is open
> * Mark all as seen when the tray is closed, not opened — allows the user to scan without losing unseen state
> * Include a thumbnail of the content the notification relates to

> **Push notification best practices**
>
> * Keep push payloads minimal — fetch full content on tap, not in the payload
> * Include `userId` in the notification payload to support multi-account scenarios
> * Group pushes by thread on iOS using `threadIdentifier`
> * Respect iOS Critical Alert restrictions — social notifications should never be critical

> **Avoiding notification fatigue**
>
> * Default to email digest for low-activity users rather than per-event push
> * Respect platform quiet hours (iOS Focus mode, Android DND)
> * Provide granular opt-out: users should be able to mute a specific community without turning off all notifications
> * Rate-limit push if a post gets hundreds of reactions — send "50+ reactions on your post" not one push per reaction

***

> [!TIP]
>
> **Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview.md) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

> **[Your next step → Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline.md)**
>
> Notifications are flowing — now ensure content quality with flagging, AI moderation, and admin review.

Or explore related guides:

> **[User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph.md)**
>
> Follow activity that drives notification events

> **[Comments & Reactions](/use-cases/social/comments-and-reactions.md)**
>
> Engagement events that trigger notification items

> **[Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline.md)**
>
> Use webhooks to notify users of moderation actions


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