Notifications

OpenTask supports two notification channels. Both are optional.

	Web Push	iOS app (APNs)
Over-target tasks	Yes	Yes
Reminder period notifications	No	Yes
"AI finished" and "AI couldn't process"	Yes	Yes
Bulk snooze results	Yes	Yes
Action buttons	No	Yes
Repeats replace the previous notification	No	Yes
Breaks through Focus / Do Not Disturb	No	High and Urgent tasks

Web Push

Works on all platforms including iOS Safari. Notifications are sent directly from your server — no third-party relay.

Setup

1. Generate VAPID keys:

   npx web-push generate-vapid-keys

2. Add the keys to your environment:

   # docker-compose.yml
   environment:
     VAPID_PUBLIC_KEY: <your-public-key>
     VAPID_PRIVATE_KEY: <your-private-key>
     VAPID_EMAIL: mailto:you@example.com

3. Restart OpenTask. Each user enables Web Push per browser in Settings → Notifications → Web Push. On iOS, add OpenTask to the home screen first.

Web Push notifications show the task title and select the task on the dashboard when tapped (see Tapping a task notification). They have no action buttons.

iOS Native Push (APNs)

Real push notifications with interactive actions on iPhone and Apple Watch. Requires the iOS companion app and an Apple Developer Program membership ($99/year).

Setup

1. Create an APNs key in the Apple Developer portal
2. Download the .p8 key file to your server
3. Add the configuration to your environment:

   environment:
     APNS_KEY_ID: <key-id>
     APNS_TEAM_ID: <team-id>
     APNS_KEY_PATH: /path/to/AuthKey.p8
     APNS_BUNDLE_ID: com.example.opentask

   All four are required. APNS_BUNDLE_ID is the bundle ID you build the iOS app with.
4. Build and install the iOS companion app (see iOS App)

Sandbox and production tokens

APNs issues tokens for one of two environments: sandbox (development) or production. Each app reports its environment from the provisioning profile it's signed with. A build installed straight from Xcode is usually signed for development and gets sandbox tokens; App Store and TestFlight builds get production tokens. If APNs still rejects a token as invalid for the environment it was registered with (BadDeviceToken), the server retries once on the other environment and, if that works, corrects the stored registration. A token is dropped when both environments reject it, or when APNs reports it unregistered.

Widget updates

The iOS, Mac, and Apple Watch widgets (iOS 26, macOS 26, watchOS 26) register their own push token with the server (POST /api/push/apns/widget-token). When your data changes anywhere, the server sends a silent "reload" push to those widgets. These pushes use the same APNs key; no extra server configuration is needed. The server drops a token when APNs reports it is no longer valid (for example, after the app is deleted), after first retrying a BadDeviceToken on the other environment as described above.

Apple gives each device a limited daily budget of widget pushes and silently drops them once it's spent, so the server paces them for each device:

• First push after a quiet spell: sent about 2 seconds after the change, so a bulk action produces one push.
• Minimum interval: after a push, that device gets no other push for 5 minutes (OPENTASK_WIDGET_PUSH_MIN_INTERVAL_SECONDS, default 300). Changes inside the window are combined into one push at its end, so the widget always ends up showing the latest state.
• Quiet hours: a push due between the user's Sleep time and Wake time (Settings → Snooze) is held until Wake time, and overnight changes arrive in that one push. Turn this off with OPENTASK_WIDGET_PUSH_QUIET_HOURS=false.
• Only visible changes: changes the widgets don't show, such as editing only a task's notes, send no push.
• Failed sends: if a push fails with a network or APNs server error, it doesn't use up the device's minimum interval. The server doesn't retry on its own; the next change goes out after the 2-second settle.
• Mac exempt: Mac widget pushes don't count against a budget, so Mac widgets get only the 2-second settle, with no minimum interval or quiet hours.

Both variables are read when the server starts. Set the interval to 0 to push every change after the 2-second settle (useful on a development server). Widgets also refresh on their own schedule and when you open the app. See Widgets, Watch & Mac.

What gets notified

Notifications are on by default for each user. The Task reminders switch in Settings → Notifications turns them all off for that user.

Over-target tasks

When a task's target arrives, you get one notification, then repeat notifications at an interval set by its priority until you complete or snooze it:

Priority	Setting	Default
Unset	Default auto-snooze	30 min
Low	Low auto-snooze	4 hours
Medium	Medium auto-snooze	1 hour
High	High auto-snooze	15 min
Urgent	Urgent auto-snooze	5 min

Repeats count from the task's target: a High task targeted at 8:07 notifies at 8:07, 8:22, 8:37, and so on. "Auto-snooze" is the name used in Settings for this repeat interval; it doesn't change the task's target. You can override the interval for a single task in its quick panel, including turning notifications off for that task.

A recurring task that you miss stays over target (and keeps notifying) until you complete it. Reminders and quotas never send over-target notifications.

Deadlines. A one-off task with a deadline always has a target: if you didn't pick one, it gets an automatic target at your morning time 3 or 4 days before the deadline. It notifies when that target arrives, at its priority's interval, like any other target, and a snooze can't carry it past a deadline that's still ahead. Once a deadline has passed, notifications continue as before.

Task segments never notify. Tasks waiting in task segments send nothing and never count in the badge.

Grouping and limits. To avoid a flood, each check sends at most 4 individual notifications for Unset/Low/Medium tasks and 5 for High tasks, then one summary ("N more tasks over target"). Urgent tasks always get individual notifications. Higher-priority and longer-over-target tasks get the individual slots first.

In the iOS app:

• Repeats replace, not stack. Each task has one notification that is replaced on each repeat.
• Separate stacks. Reminders, ordinary tasks, and Urgent tasks each group into their own notification stack.
• Interruption levels. High tasks are time-sensitive (they break through Focus if you allow it). Urgent tasks are critical alerts, which bypass the mute switch, Do Not Disturb, and Focus. Set their volume with Critical alert volume in Settings.
• Cleared everywhere. Completing, skipping, snoozing, deleting, or moving the date of a task on any device, in the web app, or through the API removes its notification from your iPhone.
• Badge. The app icon badge (and the Mac Dock badge) shows your over-target task count. The server updates it with a badge-only push, with no banner or sound, whenever an action changes the count and when a task's target arrives. Opening the app refreshes it from the server. Apple Watch has no icon badge.

Reminders

Reminder notifications require the iOS app. Reminders are never notified one at a time. Instead, each reminder period sends one notification when it starts: the period's name as the title and a count as the body. Quota reminders count too, so the body reads "3 reminders waiting", "2 quotas waiting", or "3 reminders · 2 quotas waiting". A period with nothing waiting stays silent; a period with only quota reminders waiting still notifies. Reminders with no time of day (Anytime) don't trigger notifications. A later notification for the same period replaces the earlier one.

If a period that has already started still has reminders or quota reminders waiting, you get a follow-up at the top of the hour. There is at most one follow-up per hour for all periods. It names the most recent unfinished period and counts the others ("2 reminders waiting, and 1 earlier slot"). Follow-ups:

• are only sent between your Wake time and Sleep time (Settings → Snooze)
• are limited to 3 per day, spread out across your waking hours
• keep the last one of the day in reserve until your final period has started
• are skipped in a minute when a period's own notification is sent

Reminder notifications never change the over-target count or badge.

Quotas

Quotas never send notifications of their own and are never over target. An unmet quota's quota reminders are counted in the reminder period notifications and follow-ups above. Turning quota reminders off (in Settings, or with OPENTASK_QUOTA_PROMPTS=off on the server) takes them out of those notifications too.

"AI finished" for new tasks

When AI enrichment finishes a task or reminder you just added, you get one quiet notification saying where it landed and what AI filled in, the same information as the dashboard's Just added card. The title is the cleaned task title; the body lists the project, target, priority, recurrence, and labels:

• Added to Work · Tomorrow 9:00 AM · High
• Added to Evening · Daily at 8:30 PM (a reminder names its period instead of a project)
• Added to Inbox (AI filled in nothing)

The notification is a banner without sound and without a badge (Web Push sends it silently). It's sent to every iPhone, Mac, and Apple Watch app and every Web Push subscription.

It's sent at most once per task, and only when:

• the task was created in the last 15 minutes (re-running enrichment on an older task sends nothing)
• enrichment succeeded (a failed one sends "AI couldn't process" instead)
• the task isn't done, deleted, or a quota

Turn it off with Notify when AI finishes a new task in Settings → Notifications (on by default; enrichment_notifications_enabled in /api/user/preferences). The switch only appears when AI is enabled on the server, and it has no effect while Task reminders is off.

"AI couldn't process"

When AI enrichment fails for good on a task you added (it's retried once first), you get one quiet banner: AI couldn't process a task (or a reminder, or a quota), with the text you typed as the body, cut at 200 characters. It has the same Done and Delete buttons as "AI finished". The task keeps your text as its title and an ai-failed label, so you can fix it by hand or retry. It follows only the Task reminders switch, not the "AI finished" one, and a task that fails again after a retry notifies again.

Bulk snooze results

When a snooze-all from outside the web app (a notification's All +1hr or period button, the iPhone widget's All over target bar, the Mac's Snooze menu items, an Apple Shortcut) leaves High, Urgent, or past-deadline tasks over target, you get one quiet banner saying so, with counts only, never titles:

• Snoozed 8 tasks until 3:00 PM / 2 High still over target. Snooze again to move the High ones
• Snoozed 4 tasks until 3:00 PM / 1 Urgent still over target. Urgent can't be bulk snoozed
• Nothing snoozed / 3 Urgent can't be bulk snoozed
• Snoozed 5 tasks until 3:00 PM / 1 past deadline still over target. Snooze again to move it

Nothing is sent when nothing High, Urgent, or past its deadline was left. Surfaces that show the result themselves (the Home Screen quick actions, the Apple Watch, the Mac menu bar panel, and the web app) don't trigger it; an API caller can opt out with "notify": false on POST /api/tasks/bulk/snooze-overdue. A newer result replaces the older one. In the iOS app it carries the bulk snooze buttons.

Snoozed to deadline. When a notification button's snooze stops at a task's deadline instead of passing it, the same switch sends a quiet "Snoozed to deadline 6:00 PM" banner ("A quick snooze stops at the deadline").

Turn both off with Bulk snooze results in Settings → Notifications (on by default; sweep_feedback_notifications_enabled in /api/user/preferences). It has no effect while Task reminders is off.

Tapping a task notification

Tapping a task notification (over target, "AI finished", "AI couldn't process", or a test notification) opens the dashboard with that task scrolled into view, highlighted, and selected, so the action bar is ready for it. It doesn't open the task's quick panel. To make the task visible, the dashboard unfolds its group, clears a search or filter that hides it, and switches to the All view for that visit if Today leaves it out. A reminder opens on the Reminders page and a quota on the Quotas page. If the task is done, in the trash, or gone, a message says so.

iOS notification actions

Over-target task:

• Done — Complete the task
• +1hr — Snooze it to the next rounded hour
• All +1hr — Bulk snooze your over-target tasks by an hour
• All → Next period — Bulk snooze to the start of the next reminder period
• All → period name — Bulk snooze to that period's next start (one action per period)

Bulk snooze follows the usual rules: Urgent tasks are never included, and High tasks (and tasks past their deadline) only once nothing lower is left. From All +1hr, the task in the notification is always included. See Snooze. Every snooze, single or bulk, stops at a task's deadline if it's still ahead (see Snoozing and deadlines). The overflow summary notification offers the bulk actions only. The period actions appear once the app has loaded your periods.

Long-press a task notification for an interactive snooze grid with preset times, hour increments, and decrements. The action buttons update to show the chosen time.

"AI finished":

• Done — Complete the task
• Delete — Move the task to the trash (undoable, like any delete)

Reminder period:

• Complete all — Mark every reminder and quota reminder waiting in that period as considered. It logs no quota progress

Long-press a reminder period notification for a checklist of what's waiting: its reminders, then its quota reminders. Check the reminders you've considered. For each quota reminder, tap the dashed circle (considered) or the square next to its count (did it, which also logs progress). Then tap Complete N checked, or Complete all to consider everything else as well (quota reminders you marked "did it" still log their progress). Either way, the checklist is saved as one undo step.

Apple Watch handles notification actions directly on the wrist — no iPhone interaction needed.

Testing

Settings → Notifications has a Send Test Push button for the current browser, and Test Notifications buttons (Individual, High, Bulk, Urgent, Critical) that create a test task and notify every configured channel after a few seconds.