# Priority Levels & Critical Alerts

Every Pocket Alert message carries a priority level that decides how loudly it lands: silently in the tray, as a normal banner, or as a critical alert that wakes the device through the silent switch and Do Not Disturb.

## The five levels

| Level | Aliases | Behavior |
|-------|---------|----------|
| `silent` | `min`, `-2` | Delivered to the tray only — no sound, no vibration |
| `low` | `-1` | Quiet, no interruption |
| `default` | `normal`, `0` (or omitted) | Standard banner + sound |
| `high` | `1` | Time-sensitive — breaks through Focus and scheduled summary |
| `critical` | `max`, `urgent`, `2` | Wakes the device through the silent switch and Do Not Disturb |

Both spellings work everywhere: send `"level": "critical"` or `"level": 2`. The field is also accepted as `priority`.

## What each level does on the device

**iOS** maps levels to APNs interruption levels — `passive`, `active`, `time-sensitive` and `critical`. A `critical` alert uses Apple's critical alert entitlement, which plays sound at its own volume even when the ringer is off and Do Not Disturb is on.

**Android** maps levels to separate notification channels. `critical` uses a high-importance channel with DND bypass and a full-screen intent, so the alert takes over the screen instead of waiting in the shade.

Because each level is a separate Android channel, users can mute your routine notifications in system settings while leaving critical ones armed.

## Where you can set it

Priority resolves in this order, first match wins:

1. **Per message** — the `level` field in [Create Message](https://info.pocketalert.app/api/messages/create.md), or the priority selector in the dashboard.
2. **Per application** — a default level on the application, applied to every message that does not set its own.
3. **Per webhook** — a level on the webhook, so an incoming payload maps straight to a severity.
4. **Fallback** — `default`.

That ordering is what makes a single webhook useful for both routine and urgent events: set the webhook to `high`, and let individual calls override it upward when something actually breaks.

## Plan limits

> **Warning: Critical is a paid feature**
>
> On free plans, `critical` is automatically downgraded to `high` rather than rejected — the alert still arrives, it just does not override Do Not Disturb. Every other level works on every plan.

An unknown level name or an int outside `-2`..`2` returns `400`.

## Filtering by priority in the app

The mobile feed reads the same levels. Tap the filter icon to select one or more levels, narrow to a date range, or sort the whole feed by severity instead of time — useful when you come back to a phone with forty notifications and want the two that mattered.

## Choosing a level

A rule of thumb that keeps notifications trustworthy:

- **`critical`** — someone must act now, at any hour. Production down, security breach, freezer above temperature.
- **`high`** — needs attention within the hour. Failed deploy, payment declined, queue backing up.
- **`default`** — worth knowing today. Build finished, new signup, form submitted.
- **`low`** / **`silent`** — logging to your phone. Cron finished on schedule, nightly backup completed.

The point of levels is not to make every alert louder. It is to make the loud ones mean something.

## Related

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — the `level` field and full request reference
- [Action buttons](https://info.pocketalert.app/features/action-buttons.md) — act on the alert without opening the app
- [Scheduled delivery](https://info.pocketalert.app/features/scheduled-delivery.md) — send now, deliver later