Integrate push notifications

Check the complete list of parameters and responses of the PATCH Device Token endpoint for registering push notification tokens.

What are push notifications in Masivo?

Push notifications allow you to send timely, relevant messages directly to your customers’ mobile devices. By registering device tokens, you can target specific users or segments with personalized notifications, promotions, or alerts.

Register a device token

To enable push notifications for a customer, you need to register their device token with Masivo. This links their device to their customer profile, allowing for targeted messaging.

const customerId = "unique-customer-id";
const payload = {
  device_token: "duPXivAiS_uR1o2WGFb5fb:APA91bHYGH0sQcTWtJwSPTRB-CR47-lfo7mh_ygPVHDxBnyW45CjrV_PwVFARL8HLQ1AQOhaJfUxoPfBLtRmCZrTUYPPq9o67aXVQ-khIpiKcf4YvaFnba0",
  device_info: {
    platform: "android", // "android" | "ios" | "web"
    model: "SM-S918B", // Device model identifier
    osVersion: "34" // Operating system version
  }
};

const response = await fetch(
  `https://app.masivo.ai/api/storefront/v1/customers/${customerId}/devices`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

Understanding device tokens

device_token: A unique identifier provided by Firebase Cloud Messaging (FCM) that allows Masivo to send notifications to a specific device. This token is generated by the Firebase SDK in your mobile application.
device_info: Additional information about the device that helps with segmentation:
- platform: The operating system of the device (“android”, “ios”, or “web”)
- model: The device model name or identifier
- osVersion: The version of the operating system running on the device

Rich notification images

The optional image field on a push template is a rich notification attachment — a banner or hero image displayed alongside the title and body in the notification tray. It is not the app icon or launcher logo; those come from your native app bundle. Masivo uploads the image and includes it in the FCM/APNs payload. Supported formats are JPEG, PNG, and GIF. Keep file sizes reasonable for fast delivery on mobile networks.

Custom notification sounds

Notification sounds are native app resources, not remote media. Masivo does not accept an uploaded audio URL because neither FCM nor the operating systems can use a remote file as a notification sound. Add the same .wav file to every mobile app build that receives the template, then enter its filename in the Masivo push template. Use one of these template values:

Empty: silent notification.
default: device default sound.
order_ready.wav: custom sound bundled in the app.

Use lowercase filenames containing only letters, numbers, and underscores. Keep custom sounds below 30 seconds for iOS compatibility.

Android

Copy order_ready.wav to android/app/src/main/res/raw/. Android identifies the resource as order_ready, without its extension. On Android 8 and later, create these channels before receiving notifications:

import notifee, { AndroidImportance } from "@notifee/react-native";

await Promise.all([
  notifee.createChannel({
    id: "masivo_silent",
    name: "Silent notifications",
    importance: AndroidImportance.HIGH
  }),
  notifee.createChannel({
    id: "masivo_default",
    name: "Default notifications",
    importance: AndroidImportance.HIGH,
    sound: "default"
  }),
  notifee.createChannel({
    id: "masivo_order_ready",
    name: "Order ready notifications",
    importance: AndroidImportance.HIGH,
    sound: "order_ready"
  })
]);

Masivo derives the custom channel ID from the filename: order_ready.wav becomes masivo_order_ready. Android channel sound behavior cannot be changed after a channel is created, and users can override it in system settings.

iOS

Add order_ready.wav to the main application target’s Copy Bundle Resources build phase. Masivo sends the complete filename in the APNs sound field. Rebuild and reinstall the native app after adding a sound. An over-the-air JavaScript update cannot add native audio resources.

Device tokens can change over time. Your app should update the token in Masivo whenever the FCM SDK provides a new token to ensure uninterrupted delivery of notifications.

User segmentation with push notifications

Registering device tokens enables powerful audience segmentation capabilities:

Target by demographics: Send notifications to specific user segments based on demographics, location, or behavior
Campaign-specific messaging: Tailor notifications to specific marketing campaigns or loyalty programs
Engagement tracking: Monitor which notifications drive user engagement and conversions

Best practices

Always request push notification permissions at appropriate times in the user journey
Refresh and update device tokens regularly to maintain delivery reliability
Provide clear opt-out options to respect user preferences
Test notifications across different device types before sending to your entire audience
Keep messages concise and actionable to improve engagement

API Documentation

Endpoints

Guides

Resources

Integrate push notifications

What are push notifications in Masivo?

Register a device token

Understanding device tokens

Rich notification images

Custom notification sounds

Android

iOS

User segmentation with push notifications

Best practices

​What are push notifications in Masivo?

​Register a device token

​Understanding device tokens

​Rich notification images

​Custom notification sounds

​Android

​iOS

​User segmentation with push notifications

​Best practices

What are push notifications in Masivo?

Register a device token

Understanding device tokens

Rich notification images

Custom notification sounds

Android

iOS

User segmentation with push notifications

Best practices