We're excited to introduce new additions to Appwrite Messaging that give you greater control over how you send and handle push notifications in your app. The push notification API now affords you finer control over both how and when your notifications are delivered. You can run background updates silently, send critical alerts that bypass Do Not Disturb, and manage delivery priorities. These changes enable you to handle common scenarios - such as data syncs, urgent alerts, and battery-conscious updates more effectively.
Here's a quick overview of the new features:
Background updates (iOS)
We're now supporting Apple's background notifications through the contentAvailable parameter. This lets your iOS app process updates in the background without displaying notifications to users. Background notifications are useful for data syncs, content updates, and state changes that don't require user interaction.
When you set contentAvailable, your app wakes up in the background to handle the notification payload. This works well for messaging apps that need to fetch new messages, news apps refreshing content, or any app that needs to update data periodically. Since no UI is shown to users during background updates, you can omit both the title and body.
A few things to keep in mind when using background notifications:
You'll need to configure your app to handle background processing using Background Modes in Xcode.
Set the notification priority to normal to ensure proper background delivery.
Apple limits background notifications to about 2-3 per hour to preserve battery life.
For Android users, you can achieve similar functionality by sending a data-only notification (just omit the title and body).
To implement background notifications, set contentAvailable to true and handle the application:didReceiveRemoteNotification:fetchCompletionHandler: method in your app.
Critical alerts (iOS)
Sometimes, users need to see a notification even when their phone is on Do Not Disturb. The new critical parameter attempts to mark the notification as critical, which can bypass silent and do not disturb settings when approved. To use critical alerts, you'll need to request the critical alert entitlement from Apple through your developer account - just visit Apple's developer portal and fill out a brief form explaining your use case.
Critical alerts are essential for apps that handle time-sensitive or safety-related notifications, such as:
Healthcare apps sending urgent medical alerts
Home security apps warning about break-ins
Connected device apps alerting about smoke or carbon monoxide detection
Emergency response apps sending evacuation notices
Financial apps warning about suspicious transactions
Priority controls
You can now set notifications as either normal or high priority:
Normal priority: The system delivers these at convenient times based on battery life and may group notifications together.
High priority: These go out right away - useful for time-sensitive updates.
Other updates
Badge numbers (iOS): Set a number to display on your app icon to show pending notifications. Set it to 0 to clear existing badges. Must be an integer.
Data payload: Both title and body are now optional fields. This gives you more flexibility, especially for background updates.
Technical details
These new parameters work with our existing createPush and updatePush endpoints. We pass these parameters directly to the underlying push notification services (APNs for Apple and FCM for Android) - you just need to set the parameters you want.
Here are some examples to get you started:
Example 1: Background update for fetching new messages
Future result = await messaging.createPush(
messageId: 'background-sync-1',
title: null, // Optional for background updates
body: null, // Optional for background updates
topics: [], // Optional: Send to specific topics
users: [], // Optional: Send to specific users
targets: [], // Optional: Send to specific devices
data: { // Optional: Custom data payload
'type': 'message_sync',
'lastSyncId': '123'
},
contentAvailable: true, // iOS background updates
priority: 'normal', // Required for background updates
);
Example 2: Critical alert for security breach
Future result = await messaging.createPush(
messageId: 'security-alert-1',
title: 'Security Alert',
body: 'Unusual activity detected at front door',
topics: [], // Optional: Send to specific topics
users: [], // Optional: Send to specific users
targets: [], // Optional: Send to specific devices
data: { // Optional: Custom data payload
'type': 'security_alert',
'deviceId': 'front_door_cam'
},
badge: 1, // Must be an integer
critical: true, // iOS-only parameter
priority: 'high', // High priority for critical alerts
);
Example 3: Normal notification for all platforms
Future result = await messaging.createPush(
messageId: 'chat-message-1',
title: 'New Message',
body: 'Sarah sent you a photo',
topics: [], // Optional: Send to specific topics
users: [], // Optional: Send to specific users
targets: [], // Optional: Send to specific devices
data: { // Optional: Custom data payload
'chatId': '456',
'messageType': 'photo'
},
badge: 3, // Integer for iOS, ignored on Android
priority: 'normal', // Normal priority delivery
);
Each example shows different combinations of the new parameters based on common use cases. Note that some parameters like critical and badge are iOS-specific, while others work across platforms. You can mix and match these parameters based on your needs.
Documentation and resources
See the full implementation details in our docs
Check out our best practices for sending push notifications
Watch the feature walkthrough
Learn more about Messaging
If you run into any issues or have questions about implementing these features, check the documentation or reach out to us through our support channels.