Skip to Content
Pocket Notifier

Android notifications

Channels per priority, grouping per project, what a tap does, actions, inline reply and permissions.

Channels

Decided One channel per priority. They are created on first launch and defined as ANDROID_CHANNELS in packages/contract/src/push.ts.

PriorityChannel IDNameImportanceBehaviour
5priority-5UrgentMAXPops up, long vibration, can bypass Do Not Disturb
4priority-4High priorityHIGHPops up on screen
3priority-3Default priorityDEFAULTSound and vibration
2priority-2Low priorityLOWSilent, listed in the shade
1priority-1Min priorityMINSilent, collapsed, no status bar icon

Users change sound, vibration and popups per channel in System settings → Apps → notifier → Notifications. The app links to each channel's page from Settings → Notifications.

Channel IDs are permanent

Once a channel exists, Android owns its settings and the app cannot change its importance or sound. To change the defaults, a new ID is needed (priority-5-v2), and the old channel is deleted.

Do Not Disturb. The urgent channel asks to bypass Do Not Disturb, but Android only allows it after the user grants notification policy access. The app asks for it the first time a project receives a priority 5 message, never at install.

Conversations and avatars

Decided Messages can carry a conversation (what it is about, such as a project) and a sender (who sent it, such as an agent). The app then posts them the way chat apps do, with Android's MessagingStyle:

[NO]◖C  notifier · Claude              2m
        Which database for the cache layer?
        Tests pass. Ready for review.
PartComes fromAndroid
Large avatarconversation: icon, or generatedConversation shortcut icon
Small badgesender: icon, or generatedPerson icon on the message
Title lineconversation.title, then sender.nameConversation title
StackSame conversation.id in the same projectOne conversation notification

On Android 11 and later, these show in the Conversations section at the top of the shade. Users can also mark a project as a priority conversation there.

Generated avatars

Decided Without an iconUrl, the app draws an avatar: up to two initials (avatarInitials) in white on a color picked from the id (avatarColor, from a fixed 10-color palette). Both helpers are in packages/contract/src/avatar.ts, so the web dashboard and the phone draw the same avatar for the same project. No setup is needed for a new project.

With an iconUrl, the app downloads the image once, caches it, and crops it to a circle. If the download fails, it falls back to the generated avatar. Icon URLs must be HTTPS. Note that the phone fetches them directly, so the icon's host can see the phone's IP address.

Grouping

Decided Messages without a conversation stack per project (notificationGroupKey(project), which returns project:<name>):

▾ notifier · ci                         3 new
    main build failed                   3m
    Flaky test retried                  20m
    Lint warnings on PR 42              1h
  • The group summary shows the project name and the count, and opens the newest message's thread.
  • Each child uses its message ID as the notification tag, so it can be updated or cancelled exactly.
  • A group's channel is the highest priority among its children, so an urgent message is never muted by a quieter group.

Tapping

Decided A tap opens the message's thread, notifier://conversation/<projectId>/<conversationKey>, built from the push's projectId and conversationKey: the feature's thread, or the project-level thread for a message without a feature. The thread marks the conversation read and its notifications are cleared. The clickUrl is shown as an Open button on the message in the thread, and as an action on the notification itself, so it is one tap away from both. A push without those fields (from an older server) opens its clickUrl, else the inbox.

Actions

The first 3 actions appear as notification buttons Open. The rest appear only in the message screen.

ActionOn tapNeeds the app open
viewOpens the URLNo
httpSends the request from a background worker, then shows a short "Sent" or "Failed" result in the notificationNo
reply, input: falseSends an ack through responses.createNo
reply, input: trueShows Android's inline reply field, with quickReplies as suggestions, then sends the textNo

Actions with clear: true dismiss the notification once they succeed. If the network call fails, the notification stays and shows the error, so nothing is lost silently.

Permission

Android 13 and later need the POST_NOTIFICATIONS permission. The app asks right after sign-in, with a short explanation screen first. If the user declines, the inbox shows a banner with a button that opens system settings. The app does not ask again.

Read sync

When a message is read in the app or on the web, the server sends a dismiss push to the user's other devices, which cancel the matching notifications. Open

On this page