Mark Announcement Read

Beta

POST/v1/messaging/announcements/{id}/actions/read

Idempotent with Idempotency-Key header. Learn more

Marks an announcement as read for the calling user, as when they open it.

Reading also marks the announcement seen if it was not already, and leaves it in the feed until it is dismissed. Repeating the call keeps the original read time. A caller with no user of their own in the account, such as an API key, has no state to record and gets a not-found error.

Permissions requiredValues:messaging:update

The role behind your API key or agent must grant every one of these permissions.

idstring

Announcement ID.

include[]optional arrayenumValues:resource

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

idstring

Announcement ID.

objectstringenumValues:announcement

Resource type identifier.

scopestringenumValues:accountplatform

Who the announcement reaches.

account: published to a single account and shown only to that account's users.
platform: published by OpenMRP and shown to every user across all accounts.

categorystringenumValues:chat.messagechat.mentionchat.added

The kind of event the announcement is about.

Announcements draw on the same categories as notifications, such as system.broadcast or order.updated, and the category is chosen by whoever publishes the announcement. The set is open-ended and may grow over time, so clients should tolerate values they do not recognize.

titlestring

Short headline shown in the feed.

bodystringnullable

Supporting detail shown beneath the title.

statusstringenumValues:unseenseenread

Where the announcement is in its lifecycle for the calling user.

unseen: not yet surfaced to the caller.
seen: surfaced in the caller's feed but not opened.
read: explicitly opened by the caller.
dismissed: removed from the caller's feed.

The status is derived from the caller's own seen, read, and dismissed timestamps and only ever moves forward, so the same announcement can show a different status for each user in the account.

prioritystringenumValues:lownormalhigh

How prominently the announcement should be surfaced, from low through urgent.

resourceentityExpandablenullable

The resource the announcement is about, which the client can link to.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

publish_atstring (date-time)

When the announcement becomes visible in the feed.

An announcement scheduled for the future is not returned by the announcement endpoints until this time passes.

expires_atstring (date-time)nullable

When the announcement stops being shown.

Once it expires the announcement leaves every user's feed and can no longer be retrieved; an announcement with no expiry stays until each user dismisses it.

seen_atstring (date-time)nullable

When the calling user first saw the announcement.

read_atstring (date-time)nullable

When the calling user opened the announcement.

dismissed_atstring (date-time)nullable

When the calling user dismissed the announcement.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

Responses

200

Successful response for Mark Announcement Read

Mark Announcement Read

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const announcement = await client.messaging.announcements.actions.read('an_m4vwgn2t8cqs');

console.log(announcement.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const announcement = await client.messaging.announcements.actions.read('an_m4vwgn2t8cqs');

console.log(announcement.id);

200 example

{
  "id": "an_m4vwgn2t8cqs",
  "object": "announcement",
  "scope": "account",
  "category": "order.updated",
  "title": "Scheduled maintenance",
  "body": "The platform will be briefly unavailable tonight at 2am UTC.",
  "status": "unseen",
  "priority": "normal",
  "resource": {
    "id": "or_9lqo07quiwyb",
    "object": "entity",
    "type": "sales_order",
    "name": "Order #1042",
    "handle": null
  },
  "publish_at": "2026-05-10T00:00:00Z",
  "expires_at": "2026-06-10T00:00:00Z",
  "seen_at": null,
  "read_at": null,
  "dismissed_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "an_m4vwgn2t8cqs",
  "object": "announcement",
  "scope": "account",
  "category": "order.updated",
  "title": "Scheduled maintenance",
  "body": "The platform will be briefly unavailable tonight at 2am UTC.",
  "status": "unseen",
  "priority": "normal",
  "resource": {
    "id": "or_9lqo07quiwyb",
    "object": "entity",
    "type": "sales_order",
    "name": "Order #1042",
    "handle": null
  },
  "publish_at": "2026-05-10T00:00:00Z",
  "expires_at": "2026-06-10T00:00:00Z",
  "seen_at": null,
  "read_at": null,
  "dismissed_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Mark Announcement Read

Authorization

Path Parameters

Query Parameters

Returns

Responses