Messages messages

In-app messages and announcements; admins publish announcements and tenants read and mark them as read.

Pick an endpoint to see its example call on the right.

MessagesAuthentication: Admin only7 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/messagesList messages

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
typestring Message type, such as announcement or cert-expire.
site_idinteger Site ID
site_idsstring Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
readboolean Read filter. false returns unread only (same scope as the bell unread count, announcements excluded) and true returns read only within that scope; omit for no filter. For administrators the state is the administrator's own.
POST/api/v2/messagesPublish announcement

Authentication: Admin only

Request body application/json

FieldTypeDescription
contentstring Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed.
is_externalboolean When true, clicking jumps to url and url is required; otherwise content is required.
is_importantboolean Whether to mark it as important (an "Important" tag before the title).
is_pinnedboolean Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order.
is_popupboolean Whether to show it as a pop-up.
is_showboolean Whether the message is visible.
sortinteger Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order.
titleRequiredstring Message title.
urlstring Link opened on click when is_external is true.
PUT/api/v2/messages/pin-orderReorder pinned announcements

Authentication: Admin only

Request body application/json

FieldTypeDescription
idsRequiredinteger[] Pinned announcement ids in the desired order (first is shown first).
POST/api/v2/messages/readMark messages as read

Authentication: User

Request body application/json

FieldTypeDescription
idsinteger[] Pinned announcement ids in the desired order (first is shown first).
GET/api/v2/messages/{id}Get message

Authentication: User (some parameters admin only)

PUT/api/v2/messages/{id}Update message

Authentication: Admin only

Request body application/json

FieldTypeDescription
contentstring Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed.
is_externalboolean When true, clicking jumps to url and url is required; otherwise content is required.
is_importantboolean Whether to mark it as important (an "Important" tag before the title).
is_pinnedboolean Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order.
is_popupboolean Whether to show it as a pop-up.
is_showboolean Whether the message is visible.
sortinteger Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order.
titlestring Message title.
urlstring Link opened on click when is_external is true.
DELETE/api/v2/messages/{id}Delete message

Authentication: Admin only

Messages object

FieldTypeDescription
contentstring Message body. Announcements are sanitized with an allow-list before saving (paragraphs, headings, bold, italic, lists, quotes, http(s) links); scripts, event attributes, images and tables are removed.
countinteger Number of unread messages.
created_atstring Created at
read-only
idinteger Record ID
read-only
idsRequiredinteger[] Pinned announcement ids in the desired order (first is shown first).
is_externalboolean When true, clicking jumps to url and url is required; otherwise content is required.
is_importantboolean Whether to mark it as important (an "Important" tag before the title).
is_pinnedboolean Whether it is pinned. A newly pinned one goes first in the pinned group; reorder with PUT /messages/pin-order.
is_popupboolean Whether to show it as a pop-up.
is_showboolean Whether the message is visible.
readboolean Whether the message has been read.
read-only
read_countinteger Number of tenants that have read it (tenants only, administrators excluded; returned to administrators only).
read-only
site_idinteger Site ID
read-only
sortinteger Order within the pinned group (smaller first); meaningful only for pinned announcements. The server puts a newly pinned one first; reorder with PUT /messages/pin-order.
tenant_idinteger Recipient tenant; empty for announcements.
read-only
titlestring Message title.
title_argsobject Arguments of the title key: name → string, number, or a clause {key, args} (a clause is looked up in the dictionary and filled the same way, and may nest).
read-only
title_keystring Title key (the Chinese sentence with {name} placeholders). When set, the panel looks it up in the UI-language dictionary and fills the placeholders from title_args; when null (old messages, announcements, edited titles) the panel shows title as is.
read-only
typestring announcement = announcement; others are notification types (such as cert-expire, package-expire).
read-only
updated_atstring Updated at
read-only
urlstring Link opened on click when is_external is true.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command