Notifications & Engagement

SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter

Speed run — just the code

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.

// 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. Observe tray status (refreshes after markTraySeen)
notificationTray.getNotificationTraySeen(({ data }) => {
  if (data) showBadge(!data.isSeen);
});

Full walkthrough below ↓

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.

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 and Community Platform first — notifications are triggered by feed and community events.

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

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

Get unseen notification status

Use the tray status to show an unseen indicator on your notification icon. The tray status has no count: isSeen is false when there is tray activity newer than the last time the tray was marked as seen. It refreshes when you call markTraySeen.

import { notificationTray } from '@amityco/ts-sdk';

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

Full reference → Notification Tray Status

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.

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

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

Part 2: Push Notifications

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 · Android · React Native · Flutter

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.

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

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.

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

Full reference → Register Push Notifications

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.

Get current notification settings

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

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));

Update notification module settings

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

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

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

Connect to Moderation & Analytics

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

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

Polling for notifications on a timer — This drains battery and creates unnecessary API calls. Observe the tray status instead:

// ❌ Bad — polling every 5 seconds
setInterval(() => fetchNotifications(), 5000);

// ✅ Good: observe the tray status
notificationTray.getNotificationTraySeen(({ data }) => {
  if (data) updateBadge(!data.isSeen);
});

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.

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

Dive deeper: Discovery & Engagement API Reference 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

Notifications are flowing — now ensure content quality with flagging, AI moderation, and admin review.

Or explore related guides:

User Profiles & Social Graph

Follow activity that drives notification events

Comments & Reactions

Engagement events that trigger notification items

Content Moderation Pipeline

Use webhooks to notify users of moderation actions

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

Notifications & Engagement

Quick Start: Query Notification Tray

Part 1: In-App Notification Tray

Part 2: Push Notifications

Part 3: User Notification Preferences

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps

Your next step → Content Moderation Pipeline

User Profiles & Social Graph

Comments & Reactions

Content Moderation Pipeline