How to Add Rich Push Notifications With Images and Buttons

A plain notification can announce that something happened. A rich notification can show the product, present useful actions, and take the recipient directly to the right screen. That extra capability is valuable only when the message still works on a device that hides the image, omits an action, or routes the user through sign-in.

This guide explains how to add rich push notifications with images and buttons using OneSignal for Android. It covers Android behavior, deep links, consent, identity, fallbacks, event validation, and testing. Rich content should help a person complete a specific task.

If OneSignal is not connected yet, begin with the Android push notification setup guide. Rich content comes after reliable permission, subscription, and basic tap handling.

Plan a Rich Push Notification Around One Job

Start with the action the recipient should be able to complete. “View the item,” “Track order,” and “Choose a pickup time” are clear jobs. “Increase app engagement” is an internal objective, not a useful user experience.

Decide whether the message is transactional or marketing

A transactional notification reports or helps complete an activity the user initiated. Examples include an order status update, a payment result, or an appointment change. Marketing push invites attention to an offer, new product, or editorial content. The distinction affects consent, urgency, frequency, and copy.

Do not attach promotions to security or order-status alerts. Keep service information accurate and let users control optional marketing. Legal definitions and consent requirements vary by country.

Before composing, record the event that permits the send, message category, destination, authentication requirement, frequency cap, fallback text, and success event. This prevents design, marketing, and development from implementing different campaigns.

Use rich elements only when they add meaning

A product image can identify a saved item. Buttons can separate “View order” from “Contact support.” Those elements improve comprehension.

An unrelated lifestyle image consumes bandwidth and notification space without helping the decision. Three similar buttons make the recipient stop and decode the interface. For most messages, one clear body tap and no more than two meaningful actions are easier to test and maintain.

Write the title and body first. They must communicate the essential fact without the image or buttons. Once the plain version is complete, rich elements can support it instead of carrying information that may disappear.

Build the OneSignal Message and Fallback Payload

OneSignal provides a dashboard and API for mobile push composition. Its current mobile push message guide documents platform fields and sending options, while the Create Message API reference defines programmatic payloads. Check those references when implementing because SDK and API fields can evolve.

Prepare the title, body, image, and actions

Use a concise title that identifies the subject. The body should state the important detail and the next step. Android may truncate long text depending on device, layout, font scale, and expanded state, so put distinctive information early.

Host the image at a stable HTTPS URL that is publicly retrievable by the delivery system and device. Use an appropriately compressed JPEG, PNG, or other format supported by the current OneSignal and Android implementation. Avoid a temporary signed URL that expires before a delayed notification is opened. The image should not contain the only copy of a price, date, safety warning, or action.

Give each button a short label, stable analytics identifier, specific deep link, and safe behavior when its record no longer exists. “View item” is clearer than “Open.” “Review cart” is safer than “Buy now” when price or availability can change.

Design a complete fallback

Rich media is an enhancement, not a delivery guarantee. Image retrieval can fail because the URL is unavailable, the connection is constrained, the operating system limits background work, or the notification style differs. Some surfaces show only the app icon, title, and body until expanded. Action presentation also varies across Android versions, manufacturers, lock-screen settings, and wearable or companion surfaces.

A robust fallback has three layers:

1. The title identifies the event or object.
2. The body explains what changed and offers a sensible next step.
3. Tapping the notification body opens the primary destination.

If buttons are omitted, the default tap still works. If the image is absent, the text remains accurate. If the deep-linked item is gone, the destination shows a useful state rather than a blank page.

“Blue running shoes are back in stock. Review size and availability” works without an image or button and does not promise continued availability.

Protect server credentials

Manual tests can use the OneSignal dashboard. Automated sends should originate from a trusted backend that protects API credentials and logs the authorizing event. Never expose a sending key in JavaScript, a WebView, or an APK. The OneSignal JavaScript bridge guide covers safe identity operations, not client-side sending.

Connect Buttons and Deep Links Safely

A rich notification is useful only if every tap reaches a valid destination. Treat the notification body and each action as separate routes that require their own tests.

Define canonical deep links

Prefer one canonical HTTPS destination for each resource, such as https://shop.example.com/account/orders/1842 or https://shop.example.com/products/blue-runner. Configure the Android app and WebView rules so supported links open in the app while ordinary browser visitors can still use the website.

Include only opaque record identifiers. Do not place access tokens, email addresses, or sensitive order details in the URL. The server must authorize the current signed-in user before displaying private content. Possessing the deep link is not proof of access.

When a signed-out user taps a protected link, preserve the intended destination, complete sign-in, and then continue to that page. Also define a recovery route for deleted, expired, or inaccessible records. An expired cart link could open the current cart and explain that availability was refreshed.

Map action identifiers to distinct behavior

Give buttons stable identifiers such as view_order and contact_support, rather than relying on visible labels. Labels may be localized or revised. The app can route each identifier to its corresponding destination and record which action was selected.

Avoid destructive notification actions. “Cancel order” needs authentication, current-state validation, and confirmation inside the app. A button can open that screen, but its tap should not complete an irreversible operation.

OneSignal's notification action button documentation and deep linking guide describe current configuration and click handling. Verify behavior against the OneSignal Android SDK version included in your build.

Keep identity synchronized

One person may have several subscriptions, and a shared phone may serve different accounts. After authentication, call OneSignal login with a stable opaque user ID, then logout when the session ends. Never use a rotating push token as customer identity. WebInto.app provides native LOGIN, LOGOUT, and GET_USER_STATE bridge actions.

Test this exact sequence: sign in as account A, receive A's message, sign out, sign in as account B, and verify that A's private notification is no longer targeted to the device. Identity mistakes are more serious than a missing image.

Understand Android Image and Action Limitations

Android notifications are system UI, not small web pages. Your app supplies content and intent, but Android controls layout and presentation. The official Android notification design guide explains notification anatomy, expanded styles, actions, channels, and system behavior.

Images are not always immediately visible

A large image normally uses an expanded notification style. In the collapsed state, the system may show only text and a small icon. The user may need to expand the notification to see the large image. Device makers can adjust spacing, clipping, color treatment, and expansion behavior.

Image downloads add a network dependency. Battery optimization, metered connections, stale URLs, and file size can affect them. Never use a picture as proof that an order shipped or as the sole location of a coupon. Also test Android's monochrome small notification icon in light and dark themes.

Button capacity and visibility vary

Android supports notification actions, but available space is limited. The system decides how actions appear in collapsed, expanded, heads-up, lock-screen, and wearable contexts. Long labels can be truncated. Some device states may conceal actions until expansion, and sensitive lock-screen content may be hidden by user settings.

Do not assume a fixed number of visible buttons or meaningful order. Keep the primary action available through the body tap. Specialized actions, such as inline reply, also need native support in the installed app.

Permission, channels, and interruption still apply

Android 13 and later require notification runtime permission for eligible apps. Rich content cannot bypass denial. Ask after explaining a concrete benefit, preserve app functionality after refusal, and offer a settings route without repeatedly prompting.

Use appropriately named Android channels to separate service updates from promotions. Users retain control over channel behavior. Do not abuse high-priority presentation because a marketing message has an image.

Validate Events, Audience, and Delivery Before Launch

Visual preview is only one part of quality assurance. You also need evidence that the right event produces one message for the right person.

Validate the triggering event

For an automated send, your backend should verify the event against its source of truth. An order_shipped notification should follow a valid carrier or fulfillment status transition, not an untrusted browser request. A back-in-stock message should query current inventory and recipient eligibility before enqueueing.

Use an idempotency key based on the business event, such as shipment:1842:dispatched. If a worker retries after a timeout, the same event should not create duplicate notifications. Record the event ID, recipient ID, template version, send result, and timestamp without placing sensitive payloads in broad-access logs.

Before sending, evaluate consent, current subscription state, audience membership, quiet hours, and frequency caps. A user who opted out of marketing should not receive a promotional rich push merely because they still need transactional order updates.

Build a device and state test matrix

Test at least:

• a current Android version and the oldest version your app supports;
• a representative manufacturer in addition to a standard emulator or Pixel;
• collapsed and expanded notification states;
• foreground, background, and terminated app states;
• permission granted, denied, and later disabled in settings;
• image available, slow, oversized, and unavailable;
• signed in, signed out, and switched-account states;
• each button plus the body tap;
• valid, expired, deleted, and unauthorized deep-link targets;
• light and dark themes, large text, and lock-screen privacy.

Send first to OneSignal test subscriptions. Confirm that the installed app contains the intended SDK and link configuration. A browser preview cannot prove Android action handling.

Measure outcomes without overclaiming

Delivery, display, click, and business completion are separate stages. Provider dashboards can report messaging activity, but your authenticated backend should confirm purchases, bookings, or other durable outcomes. Use campaign and action identifiers so analytics can distinguish body taps from button taps.

Compare rich and plain variants only when the audience, timing, and objective are comparable. Watch opt-outs, complaints, and failed destinations alongside clicks. A visually impressive campaign that increases notification disabling is not healthy.

Realistic Example: A Back-in-Stock Rich Push

Nadia manages an online shoe store packaged as a WebInto.app Android app. Customers can request availability alerts for a product and size. Her team uses OneSignal, but the store database remains the authority for inventory, consent, and account identity.

When customer cust_48271 requests an alert for product runner_blue in size 9, the backend records that request. It does not immediately add a broad “shoe buyer” tag and hope inventory will still exist later.

When stock arrives, a server worker validates four facts:

1. Size 9 has sellable inventory.
2. The customer still wants this alert.
3. The customer is eligible for marketing or requested service notifications under the store's policy.
4. The same restock event has not already been sent.

The OneSignal message title is “Your saved shoes are back.” Its body is “Blue Runner, size 9, is available now. Review current price and stock.” A compressed product image supports recognition. The view_product button and default body tap both open the canonical product link with size 9 preselected. A second manage_alerts action opens notification preferences.

The wording does not promise a reservation. If the image fails, the item is still named. If buttons are hidden, the body tap still reaches the product. If the customer has signed out, the public product page opens safely. If stock sells out before the tap, the page explains that it is unavailable and offers alert management.

Nadia caps restock notifications, suppresses nearby campaigns, and tests a shared phone through logout and login. Her backend records a purchase only after checkout, not after a notification click. Rich content improves recognition while identity, event validation, and cart state remain server-controlled.

Conclusion

Effective rich push notifications with images and buttons begin with accurate text, a valid event, and a useful destination. OneSignal can compose and deliver the rich payload, but Android controls presentation and may hide or omit visual elements in some contexts.

Build every message with a plain-text fallback, make the body tap useful, validate deep links and identity, and separate transactional updates from optional marketing. Then test images, actions, permissions, account changes, and expired content on real devices. For the underlying setup, review the OneSignal Android integration guide before launching automation.

FAQ

Do rich push notification images always appear on Android?

No. Large images are commonly visible in an expanded notification, while the collapsed view may show only text and an icon. Network conditions, URL availability, device software, and system restrictions can also prevent media from loading, so the title and body must stand alone.

How many action buttons should an Android notification use?

Use only the actions needed for the message, usually one or two. Android presentation varies by version, device, and surface, and labels can be truncated or hidden until expansion. Keep the primary destination available through the notification body tap.

Can a OneSignal button complete a purchase or cancel an order?

It should not complete a sensitive or irreversible operation directly. Route the user to an authenticated app screen that loads current state, explains the action, and requests confirmation. The server must authorize the final operation.

What happens when a rich notification deep link expires?

The destination should show a useful recovery state, such as the current cart, product alternative, or order list. Do not leave the user on an error page. Test deleted records, expired sessions, and changed inventory before sending.

Do users need to consent to rich push notifications?

They need the applicable Android notification permission, and marketing messages may require additional consent depending on location and your processing. Explain the value before prompting, honor category preferences and opt-outs, and keep required service alerts separate from promotions.