Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# web-push Card

# Sending Web Push notifications

Prefer the `notifyBoxholder` helper in box code over hand-writing this card —
it fans out to every configured channel (web push + Telegram). To push directly,
create a card in `_bookkeeping/output/` with the `.web-push.card` extension.

## Required frontmatter
- `title:` — Short notification title.
- `body:` — Notification body text.
- `url:` — Root-relative deep link opened on click (e.g. `/box/health`).

## Optional
- `severity:` — `info` or `alert` (default `alert`).
- `tag:` — Collapses notifications that share a tag.

## Lifecycle
1. Create the card with `status: pending`.
2. Stage and commit.
3. The push connector delivers it during `bbx finalize` to the box's
   subscribed devices.
4. On delivery (at least one device): card is deleted.
5. On failure (no device, or all sends failed): `status` becomes `failed`,
   an `error` field is added. Failed cards are not retried — fix or delete.

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.