> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/notifications/push-notifications.md).

# Push notifications

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/push-notifications.md).
{% endhint %}

Snapfix sends **push notifications** to the mobile apps about **chat** messages, **task** events, reminders and people joining a **group** or **site**. A push is either **visible**, which shows on the phone, or **silent**, which shows nothing and only tells the app to refresh its data. Each person chooses which task events send them a visible push, and whether chat messages do, in [Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md). A person can also mute a group, which makes its pushes silent for them. Tapping a visible push opens what it is about: a chat, a task in its group, an asset list or the Fix tab. The web app receives no pushes, because it never registers a push token.

## Rules

### Who gets a push

* A push goes to the people its request names, on each of their devices that has a push token ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* Who names the receivers depends on the event. Task changes made on the web go through the Laravel task API, which picks the receivers and sends the pushes itself. The apps send a push request with the receivers for their own task and group changes ([`POST /req-to-notify-user`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user)). Reminders, QR form tasks, joins and invitations are pushed by the server ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* The device that made a change gets no push. The same person's other devices get a silent push ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* A person who muted the group gets only silent pushes for it. The server reads each receiver's mute flag before it sends, and Android also hides a muted group's pushes on the phone ([Group list](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md#actions); android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/service/MyFirebaseMessagingService.java:315-319`, `:2053-2065`).
* Reminder, due-date and planner pushes read the mute from a cache that a separate script refreshes; how often it runs is not in the repos \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* A device whose "Task Notifications" switch is off gets only silent pushes, apart from the chat-tab pushes below ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).

### Which switches apply

* Each task event has its own switch, and "Task Notifications" is the master switch for them. The switches, their defaults and how the master switch turns them off and back on are in [Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#inputs).
* A task push is visible only when the receiver's switch for its event is on. An event with no switch of its own is sent silent ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* Status and priority changes each have three switches: for tasks the person created, tasks they are assigned to, and all other tasks ([Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#inputs)).
* Due-date reminders and approval requests are visible whenever "Task Notifications" is on, whatever the event switches say, unless the group is muted ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* In a task's chat only a text message can alert, under "When a Message is added to a Task". Photos, drawings, videos, voice notes and documents go out silent \[[ASK-170](https://github.com/snapfix/docs/blob/main/ASK.md#ask-170-should-photos-videos-voice-notes-and-documents-in-a-task-chat-alert)].
* "Chat Notifications" covers the chat tab: messages, mentions and reactions. The chat push route leaves out people with it off. It does not follow "Task Notifications" or the group mute ([`POST /v1/app/notification/send`](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend)).
* Devices that have never saved the newer switches, from older app versions, follow an older set of rules ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).
* The "Compliance Notifications" card is hidden on both apps and saves nothing, so no switch controls compliance pushes \[[ASK-164](https://github.com/snapfix/docs/blob/main/ASK.md#ask-164-should-compliance-changes-on-a-task-alert-people-and-may-they-switch-them-off)] ([Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#layout)).

### Which events push

* **Chat:** a message, a mention or a reaction in the chat tab pushes the other members ([Chat](https://docs.snapfix.com/product/features/chat/chat.md#notifications)).
* **Tasks:** a task created, a task assigned to the person, a message in a task's chat, a traffic light change, a priority change and a checklist that reaches 100% ([Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#inputs)).
* **Compliance:** adding or removing a compliance system on a task pushes the task's assigned and following people. The push is visible only on a priority task, for people whose priority switch applies; on other tasks it is silent \[[ASK-164](https://github.com/snapfix/docs/blob/main/ASK.md#ask-164-should-compliance-changes-on-a-task-alert-people-and-may-they-switch-them-off)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/JobSystemController.php:80-96`). See [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md).
* **Approval requests:** a task sent for approval pushes the group's admins ([Task approval](https://docs.snapfix.com/product/features/tasks/task-approval.md)).
* **Reminders:** a personal reminder, a due-date reminder and a planned-task reminder. The planned-task reminder always goes out silent, so it never shows. See [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md).
* **QR forms:** a task made from a QR form pushes "{name} Created Task" to the group's admins, the members who may view all tasks, and the task's assignees and followers ([`POST /req-to-notify-user-for-qr-job`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-for-qr-job), [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md)).
* **Joins:** a person added to a group, or an existing user added to a site, gets a push naming who added them ([`POST /req-to-notify-user-on-new-userbusiness`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-on-new-userbusiness)). A site's admins get a push when an invited user opens the invitation link or sets their password from it ([`POST /req-to-notify-site-admin`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-site-admin)).
* **Sign-ups:** the old sign-up code would tell a group's admins that a new user registered, but no running client reaches it today, and the push would be silent ([`POST /req-to-notify-group-admin`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-group-admin)).
* **Data refresh:** the "API update required" push that php-apis asks for after queued changes is never sent ([`POST /req-to-notify-user-for-api-trigger`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-for-api-trigger)).

### Devices and tokens

* Each app sends its push token and its switches when it gets or refreshes the token, and again whenever the switches are saved ([`POST /fbu_devicetoken`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-fbu_devicetoken)).
* At sign-out both apps send the device again without a token, so it gets no more pushes. Its rows stay in the device table ([`POST /fbu_devicetoken`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-fbu_devicetoken)).
* The web has the device-token endpoint in its list but never calls it, so it registers no token (web\_app\_v2 @ 0989b8e685, `src/app/shared/enums/endpoints.enum.ts:55`).
* A push needs the phone's notification permission. Without it, the settings screen shows a permission card; what each app hides is in [Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#states).

### Visible and silent pushes

* A silent push has no alert. Android shows a push only when it is not marked silent, except due-date reminders and approval requests, which it shows anyway \[[ASK-166](https://github.com/snapfix/docs/blob/main/ASK.md#ask-166-should-android-show-due-date-reminders-and-approval-requests-when-the-user-has-turned-notifications-off)] (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/service/MyFirebaseMessagingService.java:275-283`).
* Silent pushes keep the other members' apps up to date: the app reads the changed task when it gets one.
* Both apps remove bold markup from the text and count a badge of the tasks with new pushes (ios @ aa31967ac8, `NotificationService/NotificationService.swift:29-99`; android @ 86068bfeea, `MyFirebaseMessagingService.java:338-356`, `:2070-2074`).

### Tapping a push

* **iOS:** a chat push opens the chat, and a planned-task reminder opens the Fix tab. Any other push selects the group's site and opens the task in its group, under the Fix tab, or under the Plan tab with its asset list for an asset register (ios @ aa31967ac8, `Appdelegate/AppDelegate.swift:1087-1171`).
* **Android:** a task push opens the task in its group's task list, an asset register push opens the asset in its asset list, and planner and join pushes open the group list (`MyFirebaseMessagingService.java:492-521`).

### Limits and plans

* No plan or paywall check applies to pushes (apipy @ 0e83c85e5a, `model/feature_notification.py`).

### Logs

* Every push writes a row to the push log with the request, its text and receivers included. Nothing trims the log ([Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery)).

## Flow

```mermaid
flowchart TD
  event["Chat message, task event, reminder or join"] --> request["The request names the receivers"]
  request --> device{"Each receiver's device"}
  device -- "the device that made the change" --> none["No push"]
  device -- "group muted, Task Notifications off, or no switch on" --> silent["Silent push: the app refreshes"]
  device -- "its switch on, or a due-date or approval push" --> visible["Visible push"]
  silent --> android{"Android, due date or approval?"}
  android -- yes --> visible
  visible --> tap["Tap opens the chat, the task in its group, the asset list or the Fix tab"]
```

## Platforms

| Capability                                                 | Web                         | iOS                                                                                     | Android                                                                                                                                                                              |
| ---------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Receives pushes                                            | No: registers no push token | Yes                                                                                     | Yes                                                                                                                                                                                  |
| Task switches and "Chat Notifications"                     | No                          | Yes                                                                                     | Yes                                                                                                                                                                                  |
| A switch change reaches the server                         | No                          | At once                                                                                 | When the user leaves the screen                                                                                                                                                      |
| Mute a group                                               | The bell on the group list  | The bell on the group list                                                              | The bell on the group list; muted pushes are also hidden on the phone                                                                                                                |
| Tap opens                                                  | No                          | The chat, the task in its group, the asset list or the Fix tab; selects the push's site | The task in its group, the asset in its asset list, or the group list                                                                                                                |
| Due-date and approval pushes with "Task Notifications" off | No                          | Not shown                                                                               | Shown \[[ASK-166](https://github.com/snapfix/docs/blob/main/ASK.md#ask-166-should-android-show-due-date-reminders-and-approval-requests-when-the-user-has-turned-notifications-off)] |
| Warning when the system blocks notifications               | No                          | Yes                                                                                     | Android 13 and later only                                                                                                                                                            |

## Screens

* [Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md): the switches, the permission card and when each change reaches the server.
* [Group list](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md): where a group is muted, and where planner and join pushes open on Android.
* [Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md): where chat pushes open.
* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md): where a task push opens.
* [Asset list](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-list.md): where an asset register push opens.
* [Fix](https://docs.snapfix.com/how-the-apps-work/screens/tasks/fix.md): where a planned-task reminder opens on iOS.

## API and data

* [Push delivery](https://docs.snapfix.com/engineering-reference/api/notifications.md#push-delivery): how the server picks devices and decides between visible and silent.
* [`POST /fbu_devicetoken`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-fbu_devicetoken): saves a device's push token and its switches. [`GET /user-notification-settings`](https://docs.snapfix.com/engineering-reference/api/notifications.md#get-user-notification-settings): reads the switches.
* [`PUT /v1/app/notification/{businessUuid}/mute`](https://docs.snapfix.com/engineering-reference/api/notifications.md#put-v1appnotificationbusinessuuidmute) and [`/unmute`](https://docs.snapfix.com/engineering-reference/api/notifications.md#put-v1appnotificationbusinessuuidunmute): the web's group bell. The apps change the mute in their synced copy of the membership instead.
* [`POST /req-to-notify-user`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user): the apps' task and group pushes, and the web's task reminder pushes.
* [`POST /v1/app/notification/send`](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend): the chat-tab pushes from the web and the apps.
* [`POST /req-to-notify-user-on-new-userbusiness`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-on-new-userbusiness), [`POST /req-to-notify-site-admin`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-site-admin), [`POST /req-to-notify-group-admin`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-group-admin) and [`POST /req-to-notify-user-for-qr-job`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user-for-qr-job): the server's pushes for joins, invitations, sign-ups and QR form tasks.
* The reminder routes are in [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md#api-and-data).
* Tables: [`firebase_user_device_token`](https://docs.snapfix.com/engineering-reference/db/tables/firebase_user_device_token.md) (one row per device call, with the token and the switches), [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md) (the switches per person), [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (the mute flag `notifMute`) and [`tPri_Log_NotifAPIRequests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_notifapirequests.md) (the push log).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): the task events behind the switches.
* [Chat](https://docs.snapfix.com/product/features/chat/chat.md) and [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): messages, mentions and reactions.
* [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md): the "Checklist is 100% complete" push.
* [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md) and [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md): reminder, due-date and planner pushes.
* [Task approval](https://docs.snapfix.com/product/features/tasks/task-approval.md): approval requests to the group's admins.
* [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md): compliance changes on tasks.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md), [Group members](https://docs.snapfix.com/product/features/groups/group-members.md) and [Join site](https://docs.snapfix.com/product/features/onboarding/join-site.md): the mute, the receivers, and the pushes for people who join.
* [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md): the push for a task made from a QR form.
* [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md): a tapped push selects its site on iOS.

## Edge cases

* **Offline:** a switch change stays on the phone and goes out with the next push-token save ([Notification settings](https://docs.snapfix.com/how-the-apps-work/screens/notifications/settings.md#states)). A failed save shows nothing.
* **"Task Notifications" back on:** the apps restore the task switches from a copy on the phone, which can differ from the person's earlier choices.
* **Push request failures:** `POST /req-to-notify-user` answers before the push is sent; a failure later is only logged ([`POST /req-to-notify-user`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-req-to-notify-user)).
* **Bulk changes to green:** the group's admins get no push for the approval requests.
* **Who may send:** any signed-in user can push any text to any user, through the chat route and the apps' push route. The server's own push routes need no login at all.
* **Reactions:** any signed-in user can react to any task chat message, which pushes its author.
* **Former members:** on the web, people who left a chat group still get its messages as pushes.
* **Web mentions:** a web message that mentions someone pushes only the people mentioned.
* **Device data:** uncalled device-token routes return any user's or group's push devices, and two test routes push a test notification and list a user's devices with no login.
* **Malformed push:** a push whose data is not the expected JSON can crash the iOS app when it opens.
* **First launch on Android:** if deleting the old push token fails, the splash screen stays up.
* **Several sites:** each push belongs to a group; on iOS a tap switches to that group's site.
* **Time zones:** a push has no time zone. The due-date text shows the due time in the site's time zone ([`POST /job/due-reminder-notification`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-jobdue-reminder-notification)).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/notifications/push-notifications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
