---
title: "Send declarative push messages with a · Agent Wranglers"
url: https://agentwranglers.se/playbook/notifications/web-push/declarative-web-push
id: NTF-41
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 956
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Send declarative push messages with a service worker fallback

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Web push](https://agentwranglers.se/playbook/notifications/web-push.md).

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

- ID: NTF-41
- Level: Recommended
- Chapter: [Web push](https://agentwranglers.se/playbook/notifications/web-push.md)
- Rule: Send each web push payload as a declarative push message, with `"web_push": 8030`, a title and a `navigate` address. Keep a service worker `push` handler that shows the same notification for browsers without support.
- Check: A unit test builds the payload for every push type. It checks `web_push` is the number 8030, `notification.title` is set and `notification.navigate` is an `https` address on your own host. A browser test in a browser without declarative support receives the payload and still shows the notification.
- How: A declarative push message is JSON the browser shows by itself, with no service worker code running. The W3C Push API draft defines it. Safari supports it from Safari 18.4 on iOS and iPadOS, for web apps added to the Home Screen. The browser shows it even when a service worker fails or was cleared, and it cannot be abused for silent background work. Browsers without support hand the same payload to your `push` handler, which parses it and shows the notification. Use a path on your own site for `navigate`, as [Open the exact page the push is about](https://agentwranglers.se/playbook/notifications/web-push/push-deep-links.md) says. Encrypt the payload as [Send web push with VAPID and an encrypted payload](https://agentwranglers.se/playbook/notifications/web-push/web-push-vapid.md) says.

## 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
export function declarativePayload({ title, body, path }) {
  return JSON.stringify({
    web_push: 8030,
    notification: { title, body, navigate: new URL(path, 'https://example.com').href },
  });
}

self.addEventListener('push', event => {
  const { notification } = event.data.json();
  event.waitUntil(self.registration.showNotification(notification.title, { body: notification.body, data: { url: notification.navigate } }));
});
```

### Python example

```python
import json
from urllib.parse import urljoin

def declarative_payload(title: str, body: str, path: str) -> str:
    return json.dumps({
        "web_push": 8030,
        "notification": {"title": title, "body": body, "navigate": urljoin("https://example.com", path)},
    })
```

## Sources

- [W3C Push API, declarative push message](https://www.w3.org/TR/push-api/)

## Related rules

- NTF-15 [Open the exact page the push is about](https://agentwranglers.se/playbook/notifications/web-push/push-deep-links.md) in Notifications
- NTF-10 [Send web push with VAPID and an encrypted payload](https://agentwranglers.se/playbook/notifications/web-push/web-push-vapid.md) 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/web-push/declarative-web-push">Agent Wranglers notifications playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Accept push endpoints only from known push services](https://agentwranglers.se/playbook/notifications/web-push/push-endpoint-allow-list.md)
- [Web push](https://agentwranglers.se/playbook/notifications/web-push.md)