Inbox state and actions

Inbox messages expose read, seen and archive state alongside action identities. Live updates are cues to reconcile that state, and reversing inbox state does not reverse an external business action.

Read and seen status values

Value supplied to a mark operation	Requested change
MESSAGE_STATUS_SEEN	Mark the message seen.
MESSAGE_STATUS_UNSEEN	Clear its seen state.
MESSAGE_STATUS_READ	Mark the message read.
MESSAGE_STATUS_UNREAD	Clear its read state.

Returned inbox status reflects archive, read and seen state in that order of precedence. UNREAD is an update choice; reads report UNSEEN or SEEN when the message is neither read nor archived.

Inbox action identifiers

Feed entries expose two different identities:

Identity	Operations that use it
messageId	Mark or delete an inbox message.
notificationId	Archive, unarchive, complete or revert an inbox action.

Passing messageId to an operation addressed by notificationId fails to find the intended message.

Archive outcomes and retries

Operation	Scope or result
Archive or unarchive one message	An absent message returns acknowledged: true and status: "not_found".
Archive all inbox messages	Optional tags restrict the sweep; matching any supplied tag includes the message.
Archive all read inbox messages	The same tag selection applies, restricted to read messages.

After a dropped response, refresh the stored state. Retry only if the action remains the user's current choice: a delayed archive must not undo a later unarchive. Inspect status to distinguish an absent message from a completed mutation.

Action payloads and outcomes

Property or operation	Meaning
actions	Up to two call-to-action buttons on a feed entry.
isPrimary	Identifies the primary action.
ACTION_TYPE_PRIMARY / ACTION_TYPE_SECONDARY	Selects which action to complete or revert.
Revert action	Clears the inbox completion state. It does not undo a business operation; any authorized business compensation requires a separate operation.

Session fields and live events

Field	Type	Description
token	string	JWT for WebSocket auth
socketUrl	string	WebSocket URL for the inbox socket
expiresIn	string	Token validity in seconds returned for this session. Returned as a decimal JSON string.

The socketUrl + token from get-inbox-session open a Socket.IO connection that pushes inbox changes live — no polling needed for the common case. Confirm the supported client SDK and its token authentication handshake before enabling live updates. Do not copy the token into multiple headers/query parameters on the assumption they are interchangeable.

The server emits these events:

Event	Fires when
notification_received	A new message arrives — refresh the feed or prepend the payload
unseen_count_changed	The unseen badge count changes
unread_count_changed	The unread count changes

Inbox payloads may identify a message as either _id or messageId — accept both.