One recipient state across applications#
The common Messages inbox gives enrolled applications access to the same eligible messages and recipient state. The displaying application does not partition that state. A person reading a message through one enrolled client should observe the resulting state through another client using the same installation, principal and tenant boundary.
Consumers use a delegated token for the current human with the exact Messages audience. The caller does not supply a recipient selector or choose another principal. Responses are no-store, and consumer caches must clear when the user or tenant changes or signs out.
Read, refresh and mutate explicitly#
| Route | Consumer behavior |
|---|---|
GET /api/messages/v1/inbox |
Read an eligible page and unread count |
GET /api/messages/v1/inbox/changes |
Read changes after the last cursor and refresh when required |
POST /api/messages/v1/inbox/{itemId}/state |
Submit own-user read/dismiss changes with the expected revision |
GET /api/messages/v1/actions/{actionRef} |
Resolve current availability and the trusted destination |
The state request uses expectedRevision, read and dismissed. A stale mutation returns 409; refresh instead of forcing it over newer state. A null item in a change result removes a retracted, dismissed or no-longer-eligible item from the current view.
A change cursor alone is insufficient for all refreshes. Time-based expiry and identity/group changes can alter eligibility without a corresponding message-store event. The documented common-inbox contract requires periodic page/count refresh as well as cursor-based catch-up. Follow the selected version's polling values and bounds.
Opening the inbox does not implicitly mark messages read. In the richer presentation contract, All/Unread filtering happens at Messages before pagination. Explicit read/unread controls remain own-recipient mutations.
Canonical actions#
Consumers preserve the service's canonical /actions/{opaqueRef} link. The Messages browser front door authenticates the human, resolves current eligibility and navigates to the returned trusted destination. It must not accept an arbitrary return destination or forward a user token to another application.
A publisher selects an enrolled owner, target and version rather than a URL. Trusted configuration supplies the fixed HTTPS destination and resource policy. Action semantics are pinned when accepted; changing a target's semantics requires a new version/publication rather than silently retargeting an old link.
An available action can still become unavailable before navigation or submission. Recheck current authority at each owning boundary. On a failed resolution, show an unavailable/retry state without guessing another URL. Tenant switching is explicit. A navigation GET performs no domain mutation.
Presentation and display acknowledgement#
The optional Activity adapter implements the shared inbox interface for Matrix consumers. It uses trusted options, bounded cookie-free and redirect-disabled HTTP, and current-user credentials. The v1.1 presentation attachment adds localized titles/descriptions, trusted publisher identity and labels for existing actions. It cannot replace the accepted audience, permissions, target or expiry.
Some enrolled destinations support display acknowledgement. The service issues a short-lived protected ticket scoped to the item/action, recipient, tenant, destination and revision. Merely issuing the ticket or choosing a link marks nothing read. Only after the destination authorizes and displays matching context does its authenticated, antiforgery-protected backend acknowledge the display.
Messages rechecks ticket expiry, recipient revision and current eligibility. A later explicit unread or dismiss action must not be overwritten. Display acknowledgement changes read state only; it never completes a Workflow task or commits business work. Destinations without this integration retain explicit read controls.
Acceptance checklist#
Verify two enrolled clients share item IDs and read state, while another user or tenant cannot see them. Exercise expiry, retraction, stale revisions, directory failure, permission revocation and copied action URLs. For display acknowledgement, also test mismatched context, expired tickets, user replacement and explicit unread after ticket issuance. Retain appropriate Data Protection key continuity for the selected deployment model without treating key sharing as proof of every multi-instance behavior.
For actionable human work, continue with task authority and owner receipts.