PushizoDocs
Channels

iOS critical alerts, interruption levels and sound

This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application…

This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application; Pushizo generates the payload, while the entitlement and permission remain on the app side.

1. Supported iOS fields

APNs equivalents of the POST /v1/notifications fields (and template/campaign content) (packages/providers/src/apns.ts buildApnsPayload):

Pushizo fieldAPNsNote
headings, contents, subtitleaps.alert.title, .body, .subtitleResolved to the recipient's language.
ios_soundaps.sound (string)default if not given. A .caf/.aiff/.wav file name in the app bundle (≤ 30 s).
ios_badge_type + ios_badge_countaps.badge (SetTo) or hs.badge_inc (Increase, applied by the NSE)None leaves the badge untouched.
ios_categoryaps.categoryFor action buttons (buttons), the SDK registers a UNNotificationCategory.
thread_idaps.thread-idGrouping; falls back to android_group.
ios_interruption_levelaps.interruption-levelpassive, active, time-sensitive, critical (see §2).
ios_relevance_scoreaps.relevance-score0–1; iOS 15+ summary ordering.
target_content_identifieraps.target-content-idScene selection.
ios_attachments, big_picturehs.image → downloaded by the NSEPushizoExtension for rich media.
mutable_contentaps.mutable-content: 1Always sent as 1 on visible notifications (NSE: received event, media, badge increment).
content_availableaps.content-available: 1, apns-push-type: background, priority 5Silent push; no alert/sound is sent.
priorityapns-priority10 (default) immediate, 5 power-saving.
ttlapns-expirationSeconds.
collapse_idapns-collapse-idUp to 64 characters.
dataCustom keys at the payload rootKeys other than aps and hs; read via event.notification.data.

aps.sound is always written as a string; the { "critical": 1, "name": "…", "volume": … } dictionary is not generated (see §3).

2. Interruption level

ValueBehaviorRequirement
passiveNo sound/vibration, does not wake the lock screen; added to the notification list.—
active (default)Normal notification.—
time-sensitiveBreaks through Focus modes and the Scheduled Summary; plays sound.Xcode → Signing & Capabilities → Time Sensitive Notifications capability (com.apple.developer.usernotifications.time-sensitive). Users can turn it off per app in Settings.
criticalPlays sound even in silent mode and Do Not Disturb, and wakes the screen.The Critical Alerts entitlement from Apple (com.apple.developer.usernotifications.critical-alerts) and the user having granted critical alert permission.

Sending:

await hs.notifications.create({
  target: { include_external_ids: ['user_42'] },
  headings: { tr: 'Güvenlik uyarısı' },
  contents: { tr: 'Hesabınıza yeni cihazdan giriş yapıldı' },
  ios_interruption_level: 'time-sensitive',
  ios_sound: 'alert.caf',
  thread_id: 'security',
});

Only send ios_interruption_level: 'critical' to apps that have the entitlement; without it, APNs does not reject the request, but the device shows the notification at the normal (active) level.

3. Critical alert setup and current behavior

Apple side

  1. Submit a critical alert entitlement request (it requires use cases such as health, security or public safety).
  2. After approval, add the Critical Alerts capability to the App ID; set com.apple.developer.usernotifications.critical-alerts = true in the .entitlements file.
  3. Add the .criticalAlert option to the permission prompt. The Pushizo iOS SDK's Pushizo.Notifications.requestPermission call requests [.alert, .badge, .sound] (+ .provisional if provisionalAuthorization is on); it does not request .criticalAlert. Your app must therefore request critical alert permission separately:
import UserNotifications

func requestCriticalAlerts() {
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound, .criticalAlert]) { granted, _ in
        // The user manages critical alert permission with a separate switch (Settings → Notifications → app → Critical Alerts)
    }
}

This call does not conflict with the Pushizo SDK's permission tracking: the SDK reads the effective permission through UNUserNotificationCenter.getNotificationSettings and updates the subscription's push_capable value; addPermissionObserver reports the change.

Pushizo side (current behavior)

  • ios_interruption_level: "critical" → aps.interruption-level: "critical" is written.
  • ios_sound → aps.sound: "<file>" (string). The aps.sound = { "critical": 1, "name": "…", "volume": 0.0–1.0 } dictionary Apple defines for critical alerts, and therefore volume override, is not supported; the sound plays at the device's volume setting. When these fields are added, MessageContent (packages/db/src/schema/delivery.ts) and the OpenAPI contract will be extended without changing existing fields (additions are non-breaking).
  • The Notification Service Extension (PushizoExtension) preserves the aps content with mutableCopy; the interruption-level and sound values pass through the NSE unchanged. The NSE cannot raise a notification to the critical level (that is only possible with the payload + entitlement).
  • Critical and time-sensitive levels are not automatically exempt from quiet hours and frequency caps; for transactional/critical messages, send the quiet_hours_exempt: true and frequency_cap_exempt: true fields together.

4. Sound

  • ios_sound: a custom sound in the app bundle (alert.caf); default is the system sound. If the file is not found, iOS plays the default sound.
  • Silent push (content_available: true) sends no sound.
  • On Android, the equivalent is android_sound (res/raw/<name>), or the channel sound (android_channel_id) under Dashboard → Settings → Android notification categories. On Android 8+, the channel determines the sound; a per-message sound applies only when there is no channel.
  • On Web, sound is a browser/operating system setting; there is no message field.

5. Verification

  1. On a test device (a real device; the simulator has no APNs), run the app with the sandbox environment and confirm the environment matches in Dashboard → Channels → iOS Push (BadDeviceToken indicates an environment mismatch).
  2. Put the device in Do Not Disturb; a time-sensitive message should come through, while an active message should stay in the summary.
  3. In an app with the critical alert entitlement, silence the device and send ios_interruption_level: "critical"; the sound should play. Without the entitlement, the notification arrives at the normal level, which is expected behavior.
  4. In Message Tracking, check the sent → received → opened timeline; the received event is recorded by the NSE (if PushizoExtension has not been added, only opened appears).

On this page