Upsert Notification Preference

Beta

PUT/v1/messaging/preferences

This endpoint is idempotent. Learn more

Creates or replaces one of the current user's notification preferences, either their global default or the override for a single category.

The preference applies only to the account being acted in, and the category must be one the platform recognizes. Callers without a user membership in that account cannot hold preferences and are refused.

Permissions requiredValues:messaging:update

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

categoryoptional stringnullable

The notification category these settings apply to, such as chat.message.

Leave it out to set the global default used for every category without its own preference. Send null to clear.

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 off.

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.

digestoptional stringenumValues:instanthourlydaily

How often email for this category is sent. Defaults to instant.

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.

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 Upsert Notification Preference

Upsert Notification Preference

import OpenMRP from '@openmrp/sdk';

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

const notificationPreference = await client.messaging.preferences.update({
  email_enabled: false,
  in_app_enabled: true,
  push_enabled: false,
  category: 'chat.message',
  digest: 'instant',
});

console.log(notificationPreference.id);

import OpenMRP from '@openmrp/sdk';

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

const notificationPreference = await client.messaging.preferences.update({
  email_enabled: false,
  in_app_enabled: true,
  push_enabled: false,
  category: 'chat.message',
  digest: 'instant',
});

console.log(notificationPreference.id);

200 example

{
  "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"
}

{
  "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"
}

Upsert Notification Preference

Authorization

Request Body

Returns

Responses