---
title: "Show a notification for every push · Agent Wranglers"
url: https://agentwranglers.se/playbook/notifications/push-notifications/visible-push-only
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Show a notification for every push

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/notifications/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [Push notifications](https://agentwranglers.se/playbook/notifications/push-notifications)
- Rule: Every web push the service worker receives shows a notification before the handler ends. Never use push to sync data in the background without showing anything.
- How: Subscribe with `userVisibleOnly: true`, which the Push API uses to promise that every push is made visible. Safari does not support invisible pushes, and it revokes the site's permission when a push shows nothing. On Android, FCM may lower the priority of high-priority messages that show no notification. So call `showNotification()` inside `event.waitUntil()`, even when the payload is empty or the item is already read. Then show a short line such as "You have new activity". Fetch other data when the app opens instead. The full text lives in the [server-side inbox](https://agentwranglers.se/playbook/notifications/in-app-notifications/notification-inbox).
- Check: A unit test runs the service worker's `push` handler with a normal payload, an empty payload and a broken payload. Each run calls `showNotification` once. A server test finds no high-priority FCM message without a `notification` block.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
self.addEventListener('push', event => {
  const message = readPayload(event.data);
  event.waitUntil(self.registration.showNotification(message.title ?? 'You have new activity', {
    body: message.body ?? '',
    tag: message.topic,
    data: { path: message.path ?? '/notifications' },
  }));
});

function readPayload(data) {
  try { return data?.json() ?? {}; } catch { return {}; }
}
```

### Python example

```python
def fcm_message(token: str, title: str, body: str, high_priority: bool) -> dict:
    message = {"token": token, "notification": {"title": title, "body": body}}
    if high_priority:
        message["android"] = {"priority": "high"}
    return {"message": message}

def test_high_priority_messages_are_visible():
    for kind in PUSH_TEMPLATES:
        message = render_fcm(kind, SAMPLE_DATA[kind])["message"]
        if message.get("android", {}).get("priority") == "high":
            assert "notification" in message
```

## Sources

- [W3C Push API](https://www.w3.org/TR/push-api/)
- [Apple, Sending web push notifications in web apps and browsers](https://developer.apple.com/documentation/usernotifications/sending-web-push-notifications-in-web-apps-and-browsers)
- [Firebase, Android message priority](https://firebase.google.com/docs/cloud-messaging/android-message-priority)

## Related rules

- [Store every notification in a server-side inbox](https://agentwranglers.se/playbook/notifications/in-app-notifications/notification-inbox) in Notifications

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/notifications/push-notifications/visible-push-only">Agent Wranglers notifications playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep the app working when people say no](https://agentwranglers.se/playbook/notifications/push-notifications/works-without-push)
- Next: [Unlink push from the account at sign-out](https://agentwranglers.se/playbook/notifications/push-notifications/unlink-push-on-sign-out)
- [Push notifications](https://agentwranglers.se/playbook/notifications/push-notifications)