Skill Level: Any

This tutorial provides payload information for iOS and iOS10 (and later) apps.


Not what you’re looking for? Check out all our available tutorials for mobile app messaging here.




  1. Payload formats

    A payload is a property list that specifies how you want to alert your app user on their device and any custom data you provide. The property list is defined by a JSON dictionary object.

    There are three types of payload formats you can include in the SDK:

    • Mobile app message with no action category – If you have a mobile app message with no action category, only one action is possible.

    {"aps" : {
    "alert" : "Bob wants to play poker",
    "badge" : 5
  2. Payloads for iOS 10 (and later) apps

    To use the iOS 10 (and later) features in push notifications you must configure several keys in iOS 10 payloads.

    For example, you might want to use Notification Content Extensions to add media attachments for images, sound, and video to push notifications. To add media attachments, add the mutable-content flag to the aps key in the iOS 10 payload and the media-attachment key to the root of the iOS 10 payload. The notification service extension downloads the media file from the URL that you specify in the media-attachment key of the payload and attaches the file to the message.

    Several keys that you can use in iOS payload include:

    • mutable-content – To enable iOS 10 apps to process media attachments that are displayed to the user, set this flag and specify a URL in the media-attachment key on the root of the payload. Example: “mutable-content”:1,
    • media-attachment – To enable the notification service extension to download a media attachment and attach the media file to a message, specify a URL for the attachment in the media-attachment field. Example: “media-attachment”: “https://url/to/BostonMap.png”
    • Titles and subtitles: You can add titles that are displayed at the top of notifications and subtitles that are displayed within notifications. The user pulls down the notification to view additional content, where the “below the fold” section of the alert is visible and available for user interaction. To add titles and subtitles to notifications, add the title field and subtitle field to the alert key in the iOS 10 payload.
      • title – To add a title to the notification, specify a notification title in the title field. Example: “title”: “Welcome to Boston”,
        subtitle – To add a subtitle to the notification, specify a notification title in the subtitle field. Example: “subtitle”: “Thanks for
      • using Rent-A-Car. Your rental is ready”,
    • category-name – To override random category names that are generated by the SDK, add the category-name key to your payload. This key enables you to use iOS 10 (and later) features, such as Notification Content Extensions, that require predefined compiled category names.

    For information about best practices when specifying file sizes in media attachments, see Best practices for using images, videos, and audio.

    The following code example shows a basic iOS payload:

    "aps": {
    "title": "Notification title",
    "subtitle": "Notification subtitle",
    "body": "Notification body"
    "media-attachment": "https://url/to/content.mpg"
    "notification-action": {"type":"url", "value": "http://ibm.com"}, 
    "category-actions": [{"name":"foo","type":"url", "value": "http://ibm.com"}], 
    "category-name": "content-extension" 

    Go Back to the Mobile App Messaging home page.


Expected outcome

Need more help? Check out all of our available tutorials for mobile app messaging here.


Join The Discussion

Your email address will not be published. Required fields are marked *