Update and withdraw messages
Status updates are easier to read when one notification changes instead of ten piling up. Give related messages an id, then replace, withdraw, or expire them.
Group related messages#
group collects notifications under one heading in Notification Center and in History. Use one value per job or topic, for example backups or deploy-api. On iPhone you can mute a noisy group for 10 minutes or an hour from the notification's actions.
Replace a message#
Send a new notification with the same id. The earlier one leaves Notification Center, and History keeps only the newest version.
curl https://push.breezelabs.dev/v1/send \
-H 'Authorization: Bearer YOUR_KEY' \
-H 'Content-Type: application/json' \
-d '{"id":"deploy-42","title":"Deploy","body":"Step 3 of 5: running migrations"}'
An id can be up to 128 characters. Use something stable, such as a job number.
Withdraw a message#
Send delete=1 with the same id. Breeze removes the notification from Notification Center and from History.
curl https://push.breezelabs.dev/v1/send \
-H 'Authorization: Bearer YOUR_KEY' \
-H 'Content-Type: application/json' \
-d '{"id":"deploy-42","delete":1}'
A withdrawal is delivered as a background update. The system may delay it when the phone is in Low Power Mode or the app was force-quit, so don't rely on it for anything sensitive.
Expire a message#
ttl sets how many seconds a message stays in History. After that it disappears on its own. ttl=0 shows the notification without saving it.
https://push.breezelabs.dev/YOUR_KEY/One-time%20code%20482193?ttl=300
On Android, ttl also limits how long Google keeps trying to deliver: up to four weeks, and four weeks by default.
Keep messages out of History#
Send isArchive=0 to skip History for one message on iOS. To change the default for every message, open Settings in the app and choose how long History keeps pushes, or turn saving off.
Coalesce pending updates#
If the phone is offline, collapse_id keeps only the newest pending notification with that value. This saves the phone from catching up on a burst of stale updates. It doesn't guarantee exactly one delivery.