Inbox & Preferences

The inbox is the persistent, paginated history of every notification the platform sends; the source of truth whether or not the player was connected when a notification fired.

Fetching the inbox

interface GetInboxPayload {
  limit?: number;      // default 20, max 100 (values above max are clamped)
  offset?: number;    // default 0
  unreadOnly?: boolean; // filter to unread messages
}

Deterministic ordering: newest first; createdAt descending, then id as the stable tiebreaker, so pages are reproducible and no row is skipped or duplicated across pages.

const messages = await sdk.messaging.getInbox({ limit: 10, offset: 0, unreadOnly: false });

messages.forEach(msg => {
  console.log(`[${msg.type}] ${msg.title} ${msg.isRead ? '' : '(new)'}`);
});

Alongside the page, the SDK reports the total message count and the unread count for the full inbox (not the filtered page); ready for a notification badge. The summary is a separate call, so you can refresh a badge without fetching messages:

interface InboxSummary {
  total: number;       // total messages in the full inbox
  unreadCount: number; // unread across the entire inbox
}

const summary = await sdk.messaging.getInboxSummary();
console.log(`Inbox: ${summary.total} messages, ${summary.unreadCount} unread`);

Marking as read

await sdk.messaging.markAsRead('msg_12345');

GIVEN an unread inbox message
WHEN markAsRead(messageId) is called
THEN isRead flips to true and unreadCount reflects it.

GIVEN an already-read message
WHEN markAsRead(messageId) is called
THEN the call succeeds with no change (idempotent).

GIVEN an unknown messageId
WHEN markAsRead(messageId) is called
THEN the call rejects with MESSAGING_MESSAGE_NOT_FOUND.

Managing preferences

Preferences control outbound delivery channels only (email, SMS, push); the inbox and in-app real-time delivery are always on. See Messaging Overview.

const prefs = await sdk.messaging.getPreferences(); // { email: true, sms: false, push: true }
await sdk.messaging.updatePreferences({ sms: true });

Error contract

Code	Error class	HTTP status	Trigger condition	Retryable
MESSAGING_MESSAGE_NOT_FOUND	MessageNotFoundError	404	markAsRead with an unknown message ID	No

Common errors are defined once in the Error Reference.