Skip to content

Staff Announcements API

The Notification Center sends announcements to staff: each one goes to every staff member or to the ones you choose, shows in their bell, and can stay pinned on the admin dashboard until a date. See Notification Center for the user guide.

Admin calls need Module access on the Notification card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/notification/get_list

Lists the announcements, newest first. Staff with Manage announcements see all of them; the others see the ones sent to all staff or to them.

Permission: Read announcements (notification.view)

No parameters.

Returns: A list (not paged). Each announcement has id, title, message, staff (the ids of the staff members it was sent to, or null for all staff), staff_names (their names, or null), pinned_until (a Y-m-d date or null), pinned (true while pinned_until is today or later), author_id, author (the author’s name) and created_at.

Example

Request parameters:

{}

result:

[
{
"id": 31,
"title": "New phone hours",
"message": "From Monday the phone line opens at 8:00.",
"staff": null,
"staff_names": null,
"pinned_until": "2026-11-24",
"pinned": true,
"author_id": 1,
"author": "Jane Admin",
"created_at": "2026-11-17 08:45:12"
}
]

POST /api/admin/notification/get

Returns one announcement the caller may see.

Permission: Read announcements (notification.view)

Parameter Type Description
id integer, required The announcement’s id.

Returns: The announcement, with the fields of admin/get_list.

Errors:

  • Notification ID was not passed (code 9999)
  • Announcement not found (code 9999), also for an announcement sent only to other staff members when the caller lacks Manage announcements.

POST /api/admin/notification/get_pinned

Lists the pinned announcements sent to the caller (to all staff or to them), newest first: the ones the admin dashboard shows.

Permission: Read announcements (notification.view)

No parameters.

Returns: A list of announcements with the fields of admin/get_list, only those with pinned true.

POST /api/admin/notification/get_staff

Lists the staff members who can receive an announcement: active staff with access to the Notification Center and Read announcements.

Permission: Manage announcements (notification.manage)

No parameters.

Returns: A list of { id, name }, by staff id.

Example

Request parameters:

{}

result:

[
{
"id": 1,
"name": "Jane Admin"
},
{
"id": 4,
"name": "Sam Support"
}
]

POST /api/admin/notification/add

Posts an announcement and puts it in the bell of each staff member it is sent to (except the author).

Permission: Manage announcements (notification.manage)

Parameter Type Description
title string, required The title, up to 120 characters.
message string, required The message, plain text up to 2000 characters.
audience string all (default) for every staff member who can read announcements, or any other value to send it only to staff.
staff array The staff ids to send it to when audience is not all. Each must be one that admin/get_staff lists.
pinned_until string A Y-m-d date from today on: the announcement stays on the admin dashboard until the end of that day. Leave it out for no pin.

Returns: The new announcement’s id.

Errors:

  • Enter a title of up to 120 characters. (code 9999)
  • Enter a message of up to 2000 characters. (code 9999)
  • Choose the staff members who get the announcement. (code 9999) when staff is empty or names someone who cannot receive it.
  • Choose a pin date from today on. (code 9999)

Fires the onAfterAdminNotificationAdd event. The announcement also goes to chat alert destinations set to receive announcements.

Example

Request parameters:

{
"title": "New phone hours",
"message": "From Monday the phone line opens at 8:00.",
"pinned_until": "2026-11-24"
}

result:

31

POST /api/admin/notification/unpin

Takes an announcement off the admin dashboard. It stays in the list.

Permission: Manage announcements (notification.manage)

Parameter Type Description
id integer, required The announcement’s id.

Returns: true.

Errors:

  • Notification ID was not passed (code 9999)
  • Announcement not found (code 9999)

POST /api/admin/notification/delete

Deletes an announcement for good.

Permission: Manage announcements (notification.manage)

Parameter Type Description
id integer, required The announcement’s id.

Returns: true.

Errors:

  • Notification ID was not passed (code 9999)
  • Announcement not found (code 9999)

This cannot be undone.

POST /api/admin/notification/delete_all

Deletes every announcement.

Permission: Manage announcements (notification.manage)

No parameters.

Returns: true.

This cannot be undone.