Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
Notifications service (protocol v0)
Status: draft. Builds on protocol v0; breaking changes are allowed until v1. License: CC BY 4.0.
A phone mirrors its notifications to paired PCs, which show them (as toasts
and in a feed) and can dismiss them, reply to them and run their actions,
and to paired phones and tablets that offer notify.show, which show them
in their own notification shade and dismiss them there.
All messages travel on the control stream (v0 §4). Notifications are
small, latency matters more than throughput, and their order must be kept:
a notify.removed must never overtake the notify.posted it removes.
1. Capabilities
| ID | Offered by | Meaning |
|---|---|---|
notify.mirror |
phone | Sends notify.* events. Offered once the user granted notification access |
notify.live |
phone | Includes live metadata on ongoing progress, timer, and Android 16 Live Update notifications |
notify.reply |
phone | Handles notify.dismiss and notify.action |
notify.sensitive |
phone | Includes notifications Android hides from apps as sensitive (one-time codes) |
notify.show |
phone, tablet | Shows a paired phone's or tablet's notifications; a phone sends them to it as to a PC (PCs needn't offer it) |
A PC that doesn't offer anything still receives these events; a peer that doesn't know them ignores them (v0 §3.1).
2. The notification
Notification = {
key: text, // The phone's ID for it (Android: StatusBarNotification key), 1 to 256 bytes
app: text, // Package name, e.g. "com.whatsapp"
app_name: text, // User-visible app name, e.g. "WhatsApp"
title: text?, // e.g. the sender
text: text?, // The body, expanded if the app provides more
sub: text?, // Secondary line, e.g. a conversation or account name
when: int, // When it was posted, Unix milliseconds
actions: [Action], // In display order, at most 5
silent: bool, // Arrived without sound or pop-up on the phone; don't alert either
icon: bytes?, // The app's icon, PNG, at most 64 KiB (see §2.1)
image: bytes?, // The picture it shows (a photo in a message, a big picture), JPEG, at most 160 KiB
live: Live?, // Ongoing progress, timer, or Android 16 Live Update metadata (see §2.2)
conversation: Conversation?, // Notification.MessagingStyle conversation metadata (see §2.3)
}
Action = {
id: text, // Opaque to the PC, 1 to 64 bytes
title: text, // Button label, e.g. "Mark as read"
reply: bool, // Takes text (an inline reply field)
}
Text fields are plain text. Senders MUST truncate title and sub to 256
characters, text to 4,096 and action titles to 64; receivers MUST
enforce the same limits. A notification with neither title nor text is
not sent.
image is sent with every post of a notification that shows a picture,
scaled so its longest side is at most 512 pixels. Receivers drop an image
over the limit. A snapshot carries pictures only while they fit its size
budget; the rest arrive without one.
2.1 App icons
The icon of an app is sent with the first notification of that app in a
session (in notify.posted or notify.snapshot) and omitted afterwards.
Receivers keep the icons they got for the session's lifetime and may cache
them longer, keyed by package name.
2.2 Live Updates (live)
Ongoing progress bars, timers, and Android 16 Live Updates (rides, deliveries,
navigation, active builds) carry an optional live map:
Live = {
v: uint, // Schema version (currently 1)
progress: uint?, // Current progress, 0..=max
max: uint?, // Maximum progress (> 0 when determinate)
indeterminate: bool?, // True when progress is indeterminate
chip: text?, // Short status pill text (Notification.getShortCriticalText), at most 32 chars
segments: [Segment]?, // Android 16 ProgressStyle segments, at most 16
points: [Point]?, // Android 16 ProgressStyle milestone points, at most 16
chronometer: bool?, // Live elapsed or countdown timer relative to Notification.when
countdown: bool?, // True when the chronometer counts down toward Notification.when
}
Segment = {
length: uint, // Relative segment length (> 0)
color: uint?, // Optional 24-bit RGB / 32-bit ARGB color
}
Point = {
position: uint, // Position along 0..=max
color: uint?, // Optional 24-bit RGB / 32-bit ARGB color
}
Senders coalesce rapid notify.posted updates for the same key to at most
one update per second while always delivering the final update (progress >= max
or notify.removed). Receivers pin live notifications above regular
notifications in the feed and update both the feed card and the native toast in
place without re-alerting.
2.3 Conversation notifications (conversation)
Chat notifications built with Notification.MessagingStyle (RCS, WhatsApp,
Telegram, Signal, and other messaging apps) carry an optional conversation
map so the PC can present them in a unified Messages inbox alongside SMS:
Conversation = {
v: uint, // Schema version (currently 1)
title: text, // Group title or 1:1 contact name, at most 256 chars
group: bool?, // True when MessagingStyle.isGroupConversation is true
avatar: bytes?, // Conversation or contact avatar (JPEG/PNG), at most 16 KiB
messages: [ChatMessage], // Chronological (oldest first), at most 25
}
ChatMessage = {
sender: text?, // Display name (omitted when self_sent is true), at most 128 chars
text: text, // Message body, at most 4,096 chars
time: int, // Unix milliseconds
self_sent: bool?, // True when sent by the phone's user
avatar: bytes?, // Optional sender avatar (JPEG/PNG), at most 16 KiB
}
To avoid duplicating SMS threads that the SMS provider already supplies, a
phone with sms.read omits conversation when a notification from the default
SMS app matches a message already present in the system SMS/MMS provider.
Replies from the unified inbox use notify.action (§4) with the notification's
reply: true action (RemoteInput).
3. Events (phone → PC)
t = "notify.snapshot" b = { items: [Notification] }
t = "notify.posted" b = Notification
t = "notify.removed" b = { key: text }
notify.snapshotreplaces everything the PC holds for this phone. The phone sends it right after a session is established, when the user turns notifications for that PC on or off (an empty list when off), and when its notification listener (re)connects. Items are newest first, at most 100. The PC MUST NOT alert for snapshot items.notify.postedadds a notification, or replaces the one with the samekey(an update, such as a new message in the same conversation). The PC alerts unlesssilentis set.notify.removedremoves it: the user or the app dismissed it on the phone. The PC removes its toast too.
4. Requests (PC → phone)
t = "notify.sync" // one-way
t = "notify.dismiss" id = n b = { key: text }
t = "notify.action" id = n b = { key: text, action: text, reply: text? }
t = "ok" re = n
notify.syncasks for a freshnotify.snapshot, for example after the user turned notifications from this phone back on. A phone that doesn't mirror notifications ignores it.notify.dismissdismisses the notification on the phone. Dismissing one that's already gone succeeds.notify.actionruns an action. For a reply action,replyholds the text (at most 4,096 characters). The phone answersokonce the action ran, without waiting for its effect (the message being delivered, for example).
Errors: DENIED when the user turned notifications off for this PC,
NOT_FOUND when the notification or action no longer exists, UNSUPPORTED
when the phone doesn't offer notify.reply.
5. Privacy
- Notifications are sent only to PCs the user allows (the
notificationsdevice toggle on the phone) and shown only from phones the user allows (the same toggle on the PC). - Apps that mark a notification as local-only (Android
FLAG_LOCAL_ONLY) are respected: such notifications are never sent. - Implementations MUST NOT log notification content (v0 §11).