Notification channels

Notification channels are the fixed taxonomy the platform uses for push. They exist because Android channels become immutable on a device once created: importance, sound, and vibration cannot be changed later, so the channel ids and their meanings are part of the public contract. The platform defines five channels, and no more. Their ids are stable, the mobile app should fetch them from GET /notifications/channels, and a household will see fewer permissions and controls than staff see in the console. The house keeps working when the cloud is down; push delivery is separate from the rest of the system.

Why the taxonomy is fixed

On Android, the channel you create on first use is what that install keeps. If the platform later changes the channel name or meaning, existing installs do not migrate cleanly: the old channel remains with whatever the user set on it, and a new channel appears beside it. That is why the ids in this page are not examples or suggestions. They are the contract.

The same five-channel taxonomy also maps cleanly to iOS interruption levels, so one naming scheme can serve both platforms. The page is about developer-visible behavior: which channel to choose, what it means, and when not to create a new one.

The five channels

Channel id	Name shown to the user	Importance	Sound	Why it is separate
security	Security	HIGH	yes	Someone was granted or removed access; a transfer of a device was requested. A person wants this to interrupt them
device_health	Device problems	DEFAULT	yes	A device went offline, or is waiting for replacement hardware. Worth knowing today, not worth waking for
device_activity	Device activity	LOW	no	Registered, came back online, firmware updated. The recovery half of an alert belongs here — it is good news and must never buzz
household	Household	DEFAULT	yes	An invitation, a guest grant expiring. About people, not hardware
product	Product news	MIN	no	Release notes and announcements. Off by default in the app’s own settings

Rules you have to keep

A recovery is never on the same channel as the failure. If a device goes offline, that is device_health; if it comes back, that is device_activity. The recovery channel is silent by design. This avoids waking someone after the problem has already ended.

Quiet hours apply to the house, not the phone. Push is not a spoken announcement, so it is not suppressed by quiet hours. A notification that only says a device rebooted belongs on device_activity, which is silent.

Do not create a channel per device or per property. Android shows channels as a list a person scrolls through, so too many channels become unusable. Scope belongs in the payload, not in the channel.

The id is the contract. A renamed id is not a rename to an existing install; it is a new channel, and the old one remains with the user’s settings.

API and source of truth

The mobile app should use GET /notifications/channels to obtain the taxonomy instead of copying the list into the app. That prevents drift. The same five channels are also enforced on the platform side so that a notification kind always maps to a known channel.

A notification channel is not chosen later from a free-form string. It is resolved when the event is raised, by the code that knows why the event happened. That is what keeps a recovery from accidentally landing on a sounding channel.

Delivery and audience notes

Push notifications are recorded in the outbox even when delivery is unavailable. Delivery is a separate step, and if the cloud or a provider is down, the household still sees the same records later. For developers, that means the notification model is a durable event record, not a transient send attempt.

A household sees only its own notifications. Tenant staff read the console, but they are not the default recipients of household pushes. clientId and propertyId are part of the notification’s scope, and the read side uses them to narrow what each reader can see. A tenant-wide row has clientId: null and reaches every household of that tenant.

This taxonomy is also used with the push-token registry: the account’s devices can be listed, registered, and removed through POST /notifications/push-tokens, GET /notifications/push-tokens, and DELETE /notifications/push-tokens/:id. Those routes are about where delivery may go, not about which channel a notification belongs to.

What to remember when adding a notification

Choose the channel by meaning, not by device, user, or property. Use security for access changes and device transfer requests, device_health for problems, device_activity for recoveries and routine status changes, household for invitations and expiring guest grants, and product for release notes or announcements.

If a new message would reuse an existing meaning, it should use the existing id. If it would require a new id, treat that as a product-level decision, not a per-feature shortcut. On Android especially, changing the channel after release is not reversible on existing installs.

The safe rule is: the first push ship has to be correct, because the user’s device remembers it. The house keeps running without cloud connectivity, but push taxonomy does not get a second chance on a phone that has already created the channel.