Maintenance Banner

The Maintenance Banner lets you schedule informational banners that appear at the top of the admin client for all authenticated users. Use it to announce planned downtime, deployments, or any other system-level messages.

Maintenance Banner vs Maintenance Mode

Maintenance Banner (this page) shows a dismissible info banner to admin client users. It does not affect end-user access to the bots.

Maintenance Mode (see Bot Settings) disables a specific bot for end-users on public channels.

How it works

• Banners are shown automatically when active = true and the current time is before scheduledEnd.
• Each user can dismiss a banner individually. Dismissed IDs are stored in localStorage so they do not reappear after a page refresh.
• Banners are created and managed via API endpoints (see below). Changes are propagated to all connected clients without requiring a page refresh.

API Reference

The complete reference for these endpoints is available in the API documentation.

All management endpoints require an API key with the Admin role. The API key does not need to be scoped to a specific bot — it is resolved at the tenant level.

Include the key in every request:

x-api-key: <your-api-key>

See API Keys for how to create and manage API keys.

---

Data model

Field	Type	Description
_id	string	MongoDB ObjectId of the message
message	string	Banner text shown to users (min 1 character)
scheduledStart	string (ISO 8601)	When the banner becomes relevant
scheduledEnd	string (ISO 8601)	When the banner expires and stops being shown
active	boolean	Whether the banner is enabled. Defaults to true on creation
createdAt	string (ISO 8601)	Creation timestamp (auto-generated)
updatedAt	string (ISO 8601)	Last update timestamp (auto-generated)

---

GET /api/maintenance-messages/active

Returns all banners that are currently active and not yet expired. This endpoint is called by the admin client on load and does not require an API key.

Response 200 OK

[
  {
    "_id": "6620a1b2c3d4e5f6a7b8c9d0",
    "message": "Scheduled maintenance on Saturday April 19 from 02:00–04:00 UTC. The system may be briefly unavailable.",
    "scheduledStart": "2026-04-19T02:00:00.000Z",
    "scheduledEnd": "2026-04-19T04:00:00.000Z",
    "active": true,
    "createdAt": "2026-04-15T10:00:00.000Z",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  }
]

---

GET /api/maintenance-messages

Returns all maintenance messages for the tenant (including inactive and expired ones), sorted by creation date descending.

Authentication: API key · Role: Admin

curl -X GET https://<your-domain>/api/maintenance-messages \
  -H "x-api-key: <your-api-key>"

Response 200 OK — array of maintenance message objects (see data model above).

---

POST /api/maintenance-messages

Creates a new maintenance banner.

Authentication: API key · Role: Admin

Request body

Field	Required	Description
message	yes	Text content of the banner
scheduledStart	yes	ISO 8601 datetime — when the banner is scheduled to start
scheduledEnd	yes	ISO 8601 datetime — when the banner expires

curl -X POST https://<your-domain>/api/maintenance-messages \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Scheduled maintenance on Saturday April 19 from 02:00–04:00 UTC.",
    "scheduledStart": "2026-04-19T01:45:00.000Z",
    "scheduledEnd": "2026-04-19T04:00:00.000Z"
  }'

Response 201 Created — the created maintenance message object. The banner immediately appears for all connected admin users via SSE.

---

PATCH /api/maintenance-messages/:id

Updates an existing maintenance banner. All fields are optional — only the provided fields are updated.

Authentication: API key · Role: Admin

URL parameter: id — the _id of the maintenance message.

Request body (all fields optional)

Field	Type	Description
message	string	Updated banner text
scheduledStart	string (ISO 8601)	Updated start time
scheduledEnd	string (ISO 8601)	Updated end time
active	boolean	Set to false to deactivate without deleting

# Deactivate a banner immediately
curl -X PATCH https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Extend the end time of a banner
curl -X PATCH https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledEnd": "2026-04-19T06:00:00.000Z" }'

Response 200 OK — the updated maintenance message object. Connected clients are updated in real time via SSE.

Error 404 Not Found — if the message ID does not exist for the tenant.

---

DELETE /api/maintenance-messages/:id

Permanently deletes a maintenance banner.

Authentication: API key · Role: Admin

URL parameter: id — the _id of the maintenance message.

curl -X DELETE https://<your-domain>/api/maintenance-messages/6620a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: <your-api-key>"

Response 200 OK

{ "success": true }

Connected clients have the banner removed from their view in real time via SSE.

---

Tips

• Set scheduledEnd to a time slightly after the actual maintenance window ends so the banner is still visible when the window is over.
• When you need to cancel a banner that is already live, PATCH it with { "active": false } instead of deleting it — this preserves the audit log entry.
• Dismissed banners are stored per-browser in localStorage. If a user clears site data, previously dismissed banners will reappear.