Notification Preferences

Notification Preferences

Notification Preferences are how an individual user tells Piro where to reach them personally — as opposed to Triggers (called "Integrations" in the admin panel), which are shared team-level channels attached to alert configs. Preferences are what escalation actually delivers to when a user is on-call.

Notification Preferences vs. Integrations

	Integrations (Triggers)	Notification Preferences
Scope	Shared, team-wide	Personal, per-user
Configured from	Configuration → Triggers	Profile → Notification Preferences
Used for	Alert configs dispatch to these channels directly	Escalation Policies notify the on-call user through these
Channels available	Email, Telegram, Twilio SMS, Opsgenie, Pushover, Ntfy	Email, Telegram, Twilio SMS, Ntfy

Some personal channels share credentials with an Integration — e.g. a personal Telegram preference still needs a Telegram Integration configured somewhere (bot token), because that's where the platform-level credentials live. Email is the exception: it's self-sufficient from the user's own address, no Integration required.

Key properties

Field	Type	Description
Channel	PersonalNotificationChannel	Email, Telegram, TwilioSms, or Ntfy
IntegrationId	int?	Required for channels that need shared platform credentials (Telegram, TwilioSms, Ntfy). Not needed for Email
Handle	string	The personal identifier for this channel — email address, Telegram chat ID, phone number, etc.
Priority	int	Dispatch order; lower fires first (1 before 2)
VerifiedAt	datetime?	Null until the user confirms a one-time code sent to Handle. Escalation dispatch skips unverified preferences
IsAccountFallback	bool	True only for the automatically created Email preference mirroring the account email — always present, reorderable, but never deletable, and its handle stays in sync automatically when the account email changes

Source: UserNotificationPreference.cs, PersonalNotificationChannel.cs

Verification

Adding (or changing the handle of) a preference requires a one-time verification code before it becomes usable:

1. Add the channel and its handle.
2. Piro sends a one-time code to that handle (email inbox, Telegram chat, SMS, etc.).
3. Enter the code to confirm — VerifiedAt is set.

VerifiedAt is reset to null whenever Handle changes, so a typo'd or updated handle can never silently absorb a real page without being re-confirmed.

Priority and fallback ordering

Preferences are tried in ascending Priority order (1 first, then 2, and so on) when a user needs to be notified. If dispatch to the top-priority channel fails, Piro moves to the next one — giving you a fallback chain rather than a single point of failure (e.g. try Telegram first, fall back to SMS, fall back to Email).

Reorder preferences via drag-and-drop from the Profile page — this simply rewrites the Priority values.

Where to configure

Profile → Notification Preferences

Add channels, verify them with the one-time code, and drag to reorder priority. This is a personal page — every user manages their own preferences independently of what Integrations exist at the team level.

Tips

• Always keep at least one verified preference — an on-call user with zero verified channels effectively cannot be paged, even with a correct Escalation Policy pointing at their schedule.
• Put the fastest, most reliable channel for you personally at priority 1. SMS or a push channel like Ntfy typically beat email for urgency.
• Re-verify after changing a handle (e.g. a new phone number) — the system will prompt for this automatically since VerifiedAt resets.
• The auto-created Email fallback preference can be reordered to a lower priority, but cannot be removed — treat it as your guaranteed last-resort channel.

Related

• Triggers — shared team-level notification channels used by alert configs
• Escalation Policies — how on-call notifications are triggered, which then dispatch through these preferences
• Alerts — what ultimately drives a notification being sent