Mobile Push Payload Builder Guide: Craft Notifications That Work

A push notification looks simple on a phone screen: a title, a few words, perhaps an image. Behind that simplicity sits a structured message called a payload, a small data document that tells the device what to show, what sound to play, what happens when the notification is tapped, and which app data to attach. Get a field wrong and the notification may arrive silently, show the wrong screen, or not arrive at all, and debugging that failure from the phone side alone is frustrating. The Mobile Push Payload Builder helps you assemble a payload field by field, in the structure the push services expect, so you can check it before sending it into a real system. It builds and validates the structure you supply; it does not send notifications to real devices or reach a push service on your behalf.

A typical payload has two parts that are easy to confuse. The notification part is what the device displays: the title, the body text, and optionally an image, a sound, and a badge count. The data part is invisible to the user and carries information for the app: an identifier for the content, a screen to open, or a category for handling. The distinction matters because the two parts behave differently when the app is closed, in the background, or in the foreground, and because some platforms deliver the data part only when the notification part is also present. A payload that puts everything in the notification part and nothing in the data part may display correctly but open the wrong screen when tapped. A payload that puts everything in the data part may be delivered silently to the app without ever showing the user anything. Testing both parts, and the tap behaviour, is part of building a payload, not an optional extra.

Platform differences are the second source of trouble. The two major mobile platforms accept similar fields but not identical ones, and they differ in limits, such as the maximum payload size, and in how they handle images, sounds, and actions. A payload built for one platform and sent unchanged to the other may lose its image, its sound, or its action buttons. The practical approach is to build a shared core, the title, body, and data fields that both platforms need, and then add platform-specific sections for the features that differ, checking each platform's limits as you go. Payload size deserves attention on its own: a payload stuffed with extra data can exceed the service limit and be rejected entirely, so keep the data part to what the app actually needs on arrival, and fetch the rest from your server when the app opens.

Worked example

Take a sample notification, with values clearly labelled as an illustration. A shop wants to notify a customer that an order has shipped. The notification part carries the title "Your order has shipped" and the body "Order 48291 left our warehouse today and should arrive within 3 working days." The data part carries three fields: order_id with the value 48291, screen with the value "order-tracking", and type with the value "shipping-update". The total payload, counting the structure around those fields, is about 320 bytes, well within the usual limit of about 4,000 bytes for one major platform. If the team instead embedded the full order history, a product image URL, a promotional paragraph, and five extra tracking fields, the payload might reach about 3,800 bytes, still within the limit but close enough that one more field could push it over, and the app would have to parse data it never uses. The tap behaviour is also specified: tapping opens the order-tracking screen directly, using the order_id from the data part, rather than opening the app's home screen and forcing the user to search. The difference between the two payloads is not what the user sees at first glance; it is what happens on tap, and whether the payload survives the size limit.

Mistakes to avoid

The first mistake is writing titles and bodies that are too long, so the device truncates them mid-sentence and the message loses its point. The second is putting display text only in the data part, so nothing shows when the app is closed. The third is stuffing the payload with data the app could fetch on open, pushing it toward the size limit for no benefit. The fourth is never testing the tap action, so notifications open the home screen instead of the relevant content, which teaches users to ignore them. The fifth is including sensitive data in a payload: notification content can appear on a lock screen and can be logged by intermediate systems, so it should never carry passwords, tokens, full addresses, payment details, or anything a stranger glancing at a phone should not see.

Putting it into practice

Build the payload with the builder, check it against the size limit, and test the display and the tap action on both platforms before sending to real users. Keep titles short, bodies to one clear sentence, and data fields to what the app needs on arrival. Review notification copy the way you would review any message to a customer, because a notification is an interruption, and an interruption should earn its place. For related tools, the Push Notification Tester checks a finished notification, the JSON Studio helps inspect and format the payload document itself, and the companion guide on email preheader previews covers previewing outbound messages in a different channel. A well-built payload is invisible in the best sense: the user sees a clear message, taps it, and lands exactly where they expected.

Key points

• A push payload has a notification part for display and a data part for the app, and confusing them causes silent or mistargeted notifications
• Build a shared core for both platforms, then add platform-specific sections, and respect each platform's size limit
• Specify the tap action so a notification opens the relevant screen, not just the app's home screen
• Never put sensitive data in a payload, since notification content can appear on lock screens and in logs

In short: keep the payload small, separate display from data, test display and tap on both platforms, and write copy that earns the interruption.