Notification Tray Items

Query notification tray items and mark individual items as seen.

Notification tray items are paginated notification records for the signed-in user. Use this API to render an in-app notification tray and then mark individual items as seen when the user opens or views them.

Parameters

Operation	Parameter	Required	Platforms	Description
Query items	limit / pagination handle	No	TypeScript, iOS, Android	Page-size and pagination controls where supported by the platform.
Mark item seen	Item ID	Yes	TypeScript	Notification item ID to pass into markItemsSeen.
Mark item seen	lastSeenAt	Yes	TypeScript	ISO timestamp for when the item was seen.
Mark item seen	Notification tray item object	Yes	iOS, Android	Item returned by the tray item query; call markSeen() on the object.

Query Items

Query notification tray items for the signed-in user, keeping the pagination handle while the tray screen is active.

TypeScript

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

let loadNextPage: (() => void) | undefined;
let canLoadMore = false;

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

    renderResults(items);
    loadNextPage = onNextPage;
    canLoadMore = hasNextPage;
  },
);

function loadMoreNotificationItems() {
  if (canLoadMore) {
    loadNextPage?.();
  }
}

unsubscribe();

Mark an Item Seen

Mark an individual notification item seen after the user opens or views that item.

TypeScript

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

async function markNotificationItemSeen(notificationId: string) {
  await notificationTray.markItemsSeen([
    {
      id: notificationId,
      lastSeenAt: new Date().toISOString(),
    },
  ]);
}

Data Freshness

The notification tray is not real-time. Tray items are served from a short-lived server-side cache. A newly triggered notification is not guaranteed to appear the moment it happens — it becomes visible only after the server’s cache refreshes. Until then, a query returns the previously cached result. Treat the tray as eventually consistent, not live, and do not rely on a new item (or an updated count) reflecting immediately after the triggering action.

Notes

• TypeScript marks one or more items by ID through markItemsSeen.
• iOS and Android expose markSeen() on the AmityNotificationTrayItem model returned by the tray item query.
• Use the platform-specific item ID field when routing from a tray item to a target screen: TypeScript _id, iOS notificationId, and Android getId().
• Dispose live collection subscriptions or notification tokens when the notification tray screen is destroyed.

Related Topics

Notification Tray Status

Manage overall notification tray seen status.

Notification Events

Reference action and category values returned on tray items.