Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
// 1. Get notification tray items
const { data } = await notificationTray.getNotificationTrayItems({ limit: 20 });

// 2. Mark a notification as seen
await notificationTray.markSeen('notificationId');

// 3. Register push token
await Client.registerPushNotification({
  token: 'fcm-or-apns-token', platform: 'android',
});

// 4. Subscribe to real-time events
Client.onNotification((event) => {
  showBadge(event.unreadCount);
});
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 = await notificationTray.getNotificationTrayItems(
  { limit: 20 },
  ({ data: items, loading, error }) => {
    if (!loading && items) { /* render notification list */ }
    if (error) { /* handle error */ }
  },
);

​
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
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
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
import { notificationTray } from '@amityco/ts-sdk';

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

// Or mark a single item
await item.markSeen();
Full reference → Notification Tray Status
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

​
Part 2: Push Notifications

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

Get current notification settings

Read the user’s current preferences to populate a settings screen.
import { UserRepository } from '@amityco/ts-sdk';

const settings = await UserRepository.getNotificationSettings();
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.
import { UserRepository } from '@amityco/ts-sdk';

// Disable social, keep chat enabled
await UserRepository.updateNotificationSettings({
  modules: [
    { moduleType: 'social', isEnabled: false },
    { moduleType: 'chat',   isEnabled: true },
  ],
});

// Or disable all notifications at once
await UserRepository.updateNotificationSettings({ isEnabled: false });
Full reference → User Notification Settings
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

​
Connect to Moderation & Analytics

Admin Console — Push notification settings
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
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. Use real-time event subscriptions with Client.onNotification() instead.
// ❌ Bad — polling every 5 seconds
setInterval(() => fetchNotifications(), 5000);

// ✅ Good — real-time subscription
Client.onNotification((event) => {
  updateBadge(event.unreadCount);
});
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

  • 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
  • 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
  • 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