Send Notification

Beta

POST/v1/messaging/notifications

Idempotent with Idempotency-Key header. Learn more

Sends an in-app notification to a single member of an account, or announces it to everyone in the account.

A send to one member is attributed to the authenticated caller, so the recipient sees who sent it. It is accepted and then fanned out, so it reaches the recipient's feed and their connected clients shortly after the response.

An announcement to the whole account is stored as the request is accepted, carries no sender, and may only target the account you are currently acting in.

Permissions requiredValues:alerts:create

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

categorystringenumValues:chat.messagechat.mentionchat.added

The kind of event the notification represents, such as order.updated.

Categories are how clients group and filter the feed, so reuse an existing one where it fits.

targetobject

Who to send to: an account_user for a personal notification, or an account to announce to everyone in it.

typestringenumValues:account_useraccount

The kind of recipient being addressed.

account_user: one member of the account, who receives a personal notification in their feed.
account: every member of the account, who all receive a single shared announcement.

idstring

The id of the recipient, matching type: an account user id, or an account id.

An account target must be the account you are currently acting in — you cannot broadcast into another account.

titlestring

Short headline shown in the recipient's feed.

bodyoptional string

Supporting detail shown beneath the title.

priorityoptional stringenumValues:lownormalhigh

How prominently the notification should be surfaced, from low through urgent. Defaults to normal.

link_resource_typeoptional stringenumValues:accountactorentity

Type of the resource the notification should link to, such as sales_order.

Set it together with link_resource_id to point the notification at something the recipient can open; supplying only one of the two produces a notification with no link.

link_resource_idoptional string

ID of the resource the notification should link to.

objectstringenumValues:notification_send_result

Resource type identifier.

enqueuedinteger

Number of deliveries accepted for the notification.

An account broadcast is stored once as a single announcement that serves everyone in the account, so it reports 1 rather than a per-user count. Acceptance is not delivery: recipients who cannot be resolved are skipped when the notification is fanned out.

Responses

202

Successful response for Send Notification

Send Notification

import OpenMRP from '@openmrp/sdk';

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

const notificationSendResult = await client.messaging.notifications.create({
  category: 'order.updated',
  target: { type: 'account_user', id: 'acus_e5zu8bde0z3h' },
  title: 'Order updated',
  body: 'Order #1042 was updated.',
  link_resource_id: 'or_9lqo07quiwyb',
  link_resource_type: 'sales_order',
  priority: 'high',
});

console.log(notificationSendResult.enqueued);

import OpenMRP from '@openmrp/sdk';

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

const notificationSendResult = await client.messaging.notifications.create({
  category: 'order.updated',
  target: { type: 'account_user', id: 'acus_e5zu8bde0z3h' },
  title: 'Order updated',
  body: 'Order #1042 was updated.',
  link_resource_id: 'or_9lqo07quiwyb',
  link_resource_type: 'sales_order',
  priority: 'high',
});

console.log(notificationSendResult.enqueued);

202 example

{
  "object": "notification_send_result",
  "enqueued": 1
}

{
  "object": "notification_send_result",
  "enqueued": 1
}

Send Notification

Authorization

Request Body

Returns

Responses