Cheatsheet for the JSON payload of an iOS push notification
Learn the structure and configuration possibilities of a remote push notification.
17 Apr 2023 · 5 min read
When configuring the JSON payload of an iOS push notification, there are a lot of configurations options we can choose from. This guide serves as a reference and cheatsheet for those configuration options.

Basic JSON payload structure
The payload for a remote notification is a JSON dictionary with the following basic structure:
{"aps": {"alert": "Title of the push notification","sound": "default",// More configuration keys and values},"customKey1": "Some content","customKey2": "Some other content",// More custom keys and values.}
As we can see above, the JSON is a dictionary which can contain custom keys for example to provide a deep link or additional information our app may need.
To customize the push notification, we can use the aps dictionary as also shown above. Let's explore those keys and their effects on the push notification.
The alert key
The value for the alert key can either be a String or a Dictionary.
{"aps": {"alert": "Title of the push notification"}}
The configuration above produces the following push notification:

Alternatively, we can specify the notification's title, subtitle and body:
{"aps": {"alert": {"title": "Title of the notification","subtitle": "Subtitle of the notification","body": "The content of the notification."}}}
Which results in the following output:

There is also the possibility to use localized keys instead:
{"aps" : {"alert" : {"title-loc-key" : "notification.newMessage.title","title-loc-args" : [ "argument1", "argument2"],"subtitle-loc-key" : "notification.newMessage.subtitle","body-loc-key" : "notification.newMessage.body",}}}
The keys stored in Localizable.strings will automatically be used.
The badge key
The badge key is used to specify the number that will appear on the app's icon as a badge.
{"aps" : {..."badge" : 0}}
The value 0 removes the current badge.
The sound key
The sound key is used to specify the sound that will play when the notification is received which can either be a default, a custom or a critical sound.
Default sound
{"aps" : {..."sound" : "default"}}
The example above plays the system sound.
Custom sound
{"aps" : {..."sound" : "applause.wav"}}
As shown above, we can specify a sound file in the app's main bundle in .aiff, .wav or .caf file format to be played when the notification is shown.
Critical sound
A critical sound plays even if Do Not Disturb is turned on or the device is muted. Only apps approved for the critical alerts entitlement are allowed to send critical alerts. For example:
{"aps" : {..."sound": {"critical" : 1,"name": "default", // or name of a sound file in the app's main bundle"volume": 1 // value between 0 (silent) and 1 (full volume)}}}
The thread-id key
An identifier for grouping related notifications, for example:
{"aps" : {..."thread-id": "com.tanaschita.newArticle"}}
The iOS system will automatically sum up notifications with the same thread-id into a group when showing them in the notification center.
The category key
The category key can be used to add custom actions to the notification.
{"aps" : {..."category" : "drinkingReminderCategory"}}
Checkout this article on how to add custom actions for iOS notifications to learn more.
The content-available key
The content-available key declares the notification as a background notification.
A background notification doesn't display an alert, play a sound or show a badge. It wakes the app in the background and gives it time to initiate downloads and update its content.
{"aps" : {"content-available" : 1}}
Check out the official documentation on pushing background updates to your app to learn more about background notifications.
The mutable-content key
The mutable-content key can be used if we need to modify the payload of a remote notification before it's shown to the user, for example to decrypt data or to incorporate additional content based on data within the application.
{"aps" : {"mutable-content" : 1,...},}
Modifying a remote notification requires a notification service app extension, which receives the contents of the notification before is is displayed to the user to be able update the notification payload.
Check out the official documentation on modifying content in newly delivered notifications to learn more.
The interruption-level key
The interruption-level key represents the importance and delivery timing of a notification:
{"aps" : {"interruption-level" : "active",...},}
The following values are available:
- active - presents the notification immediately, lights up the screen, can play a sound.
- critical - presents the notification immediately, lights up the screen, bypasses the mute switch to play a sound.
- passive - adds the notification to the notification list without lighting up the screen or playing a sound.
- timeSensitive - similar to active notifications, but can break through system controls such as Notification Summary and Focus. The user can turn off the ability for time sensitive notification interruptions.
The relevance-score key
The relevance score value is a number between 0 and 1, that the system uses to sort the notifications from the same iOS application.
{"aps" : {"relevance-score" : 1,...},}
The highest score gets featured in the notification summary.

Newsletter
Like to support my work?
Say hi
Related tags
Articles with related topics
Latest articles and tips