List Notification Preferences

Beta

GET/v1/messaging/preferences

This endpoint is idempotent. Learn more

Lists the current user's notification preferences for the account they are acting in: their global default plus any per-category overrides.

Only preferences the user has explicitly set are returned, so an empty list means everything falls back to the standard behavior — in-app notifications on, email and push off.

Permissions requiredValues:messaging:read

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

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of notification_preference

Resources in this page.

idstring

Preference ID.

objectstringenumValues:notification_preference

Resource type identifier.

categorystringnullableenumValues:chat.messagechat.mentionchat.added

The notification category this preference applies to.

A preference with no category is the user's global default, used for every category they have not set a specific preference for.

in_app_enabledboolean

Whether notifications in this category appear in the user's in-app feed.

A direct @mention is always delivered in-app, even when this is disabled.

email_enabledboolean

Whether notifications in this category are also emailed to the user.

Email is additionally suppressed for a conversation the user has muted, and only sent on the cadence set by digest.

push_enabledboolean

Whether notifications in this category are also sent as push notifications.

Push delivery is not available yet; the choice is stored for when it is.

digeststringenumValues:instanthourlydaily

How often email for this category is sent.

instant: send an email as soon as an eligible notification occurs.
hourly: collect eligible notifications into a single hourly email.
daily: collect eligible notifications into a single daily email.
off: never send email for this category, even when email is otherwise enabled.

This governs email only; in-app delivery is unaffected. Batched sending is not running yet, so hourly and daily currently hold email back in the same way as off.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

Responses

200

Successful response for List Notification Preferences

List Notification Preferences

import OpenMRP from '@openmrp/sdk';

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

const listNotificationPreference = await client.messaging.preferences.list();

console.log(listNotificationPreference.data);

import OpenMRP from '@openmrp/sdk';

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

const listNotificationPreference = await client.messaging.preferences.list();

console.log(listNotificationPreference.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/preferences?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoibmZwZl90aHI2d2c1Njl0eHMiLCJkIjoiZiJ9.Bgj3Fi0D8nv3SUXSetVfZ4WFBeyFdPpZ0E8p4A6FyOE",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "nfpf_thr6wg569txs",
      "object": "notification_preference",
      "category": "chat.message",
      "in_app_enabled": true,
      "email_enabled": true,
      "push_enabled": false,
      "digest": "instant",
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/preferences?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoibmZwZl90aHI2d2c1Njl0eHMiLCJkIjoiZiJ9.Bgj3Fi0D8nv3SUXSetVfZ4WFBeyFdPpZ0E8p4A6FyOE",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "nfpf_thr6wg569txs",
      "object": "notification_preference",
      "category": "chat.message",
      "in_app_enabled": true,
      "email_enabled": true,
      "push_enabled": false,
      "digest": "instant",
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

List Notification Preferences

Authorization

Returns

Responses