Notifications

Put a notification in employees' activity feed in the app, for example "Your shift on Friday changed" from a rota system. Target groups, individual users, or both. Every recipient gets their own notification.

The notification appears in the activity feed only; no push notification is sent. When you include a url, tapping the notification opens it.

Required scope: write:notifications

Endpoints

POST

/api/open/v1/notifications

Send a notification to the activity feed of groups and users

Send a notification

curl -X POST https://customer.monotree.com/api/open/v1/notifications \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Your shift on Friday changed",
    "body": "You now start at 08:00. Open the rota to confirm.",
    "groups": [12, 40],
    "users": [4012],
    "url": "https://rota.example.com/shifts/991",
    "source": "Rota"
  }'

Field	Type	Notes
`title`	string	Required. The main line of the notification. Max 80 characters, one line.
`body`	string	Required. The text under the title. Max 255 characters.
`groups`	array of integers	Group IDs to target. Required unless `users` is sent. See Who receives it.
`users`	array of integers	User IDs to target. Required unless `groups` is sent.
`url`	string	Optional. Opened when the employee taps the notification. Max 100 characters. See Links. Without a `url`, the notification can't be tapped.
`source`	string	Optional. The name of the system that sent the notification, for example `Rota`. Max 20 characters, one line.

Title and body are shown as plain text: Markdown and HTML are not rendered.

The title, url and source are stored together, and quotes and backslashes take up extra room there. A request with many of those characters and every field near its limit can be rejected with 422 on title, even though each field is within its own limit. Shorten one of the fields.

Who receives it

Groups: an employee must be in at least one of the listed groups of each group type you send. Two departments reach the people in either department. A department and a profession reach only the people who are in both.
Users: exactly the listed users, whatever groups they are in.
Both: everyone matched by groups, plus everyone in users. An employee matched both ways gets one notification, not two.

Deactivated employees, employees who haven't registered yet, and bots are skipped. Employees who have turned notifications off don't get it. An unknown or deleted group or user ID returns 422.

Response

{
  "data": {
    "recipients": 42
  }
}

recipients is the number of employees your groups and users matched. The notifications are created in the background right after the response, so they can take a moment to appear. Employees who have turned notifications off are counted but don't get one. With 0 recipients, nothing is sent.