Show alerts over a screen

Follow these steps in your own Denframe. This website never connects to your household, your accounts or your devices, and never asks for your credentials.

1. 1

   Open the Alerts page

   In Studio, open Sources, then Alerts. There is nothing to connect: alerts arrive on their own and are shown over whatever is on screen.

   The page shows a picture of an alert over a dashboard, the Webhook address, and Recent alerts, each with its severity and status: Queued, Active, Acknowledged or Expired.

2. 2

   Send a test alert

   Choose Send a test alert. Enter a Source such as doorbell and, optionally, a Dedupe key (optional) such as front-door.

   Pick a Severity and set Duration in minutes, from 1 to 1440. Write a Title (up to 160 characters) and a Detail (up to 500), both plain text.

   Under Screens, leave All screens to send it everywhere, or tick the screens it should appear on. Choose Send alert; the page says where it went.

   Send a test alert from here rather than setting off a real doorbell, leak sensor or alarm to see one.

3. 3

   Know which alert wins

   A screen shows at most one alert at a time, over its dashboard.

   Severity	Use it for
   Advisory	Something worth knowing, such as a delivery or a timer
   Warning	Something to act on soon
   Critical	Something urgent, such as a leak or someone at the door

   Critical wins over Warning, and Warning over Advisory. Between alerts of the same severity, the one that started first wins.

   Sending the same source and dedupe key again while an alert is active or queued adds an occurrence to it instead of making a second alert, and it keeps the highest severity sent. The page shows the count.

4. 4

   Let it clear or acknowledge it

   An alert goes away when its time runs out, or when you choose Acknowledge beside it under Recent alerts. By default a screen can’t dismiss an alert itself; an alert sent through the webhook with allow_receiver_dismiss: true shows Dismiss on a touch screen that supports it, and Escape dismisses it too.

   When it goes, the screen returns to the same place in its playlist with the time that was left, unless that dashboard’s schedule ended meanwhile. While an alert is up, the screen’s playback controls are unavailable.

   Remove deletes a record from the list. Denframe keeps at most 500 finished alerts and removes those older than 30 days.

5. 5

   Send alerts from an automation

   Choose Copy address beside Webhook for the full address. A doorbell, weather service, leak sensor or timer posts JSON to it, with Denframe’s management bearer token in the Authorization header: never in the address.

   For an automation, set DENFRAME_API_TOKEN (at least 20 characters) on the Denframe server before starting it, and keep the token in the automation’s protected settings.

   {
     "source": "doorbell",
     "dedupe_key": "front-door",
     "severity": "critical",
     "title": "Someone is at the door",
     "detail": "Front doorbell rang",
     "target_device_ids": [],
     "starts_at": "2026-09-03T12:00:00Z",
     "expires_at": "2026-09-03T12:05:00Z"
   }

   curl -X POST "$DENFRAME_ALERT_URL" \
     -H "Authorization: Bearer $DENFRAME_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data @alert.json

   • On the webhook, source, dedupe_key, severity, title, detail and expires_at are required (only the test sheet makes the dedupe key optional), and starts_at defaults to the moment it arrives. source takes letters, numbers, dots, colons, underscores and hyphens. Each source may send at most 20 alerts a minute.
   • An empty target_device_ids list means every screen. Once any repeat of an alert is for every screen, the alert stays on every screen.
   • starts_at and expires_at need a time zone, and the window must be between one second and 24 hours. Set them to the time you send it.

   Images are off by default. To allow a picture in the optional image_url field, such as from a camera, set DENFRAME_ALERT_IMAGE_HOSTS to its exact host names, comma-separated with no scheme, port or path, such as camera.local, before starting Denframe. Only HTTP(S) image addresses on those hosts are accepted.

6. 6

   Check the alert

   Look at a screen you sent the test alert to: the alert’s title and detail are over its dashboard. Under Recent alerts, it reads Active with when it expires.

   Choose Acknowledge, or wait for the duration to pass: the screen goes back to its dashboard, and the alert reads Acknowledged or Expired.