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

FCM data payload

When Masivo delivers a visible push, Firebase receives a notification block (title, body) plus a data map. Every data value is a string. Image and sound are platform fields (Android/APNs), not keys inside data. Use data when the customer opens the notification (deep link, attribution, or PUSH_OPENED). A dashboard test send is not the same as a journey send — do not assume the keys are interchangeable.

This section covers visible marketing pushes. Silent in-app wake payloads use masivo_type and are documented in the React Native SDK.

Data keys

Key	When it is present	Meaning
`accountId`	Always	Masivo account that sent the push
`notificationId`	Test, scheduled audience, manual API	Test is `"test"`. Manual API is `"manual"`. Scheduled audience sends the delivery history id
`customerId`	Journey and manual API	Customer who received the push
`link`	Template has a destination	Short URL on the account custom domain (`https://{domain}/l/{path}`)
`redirect_android`	Push settings	Store / app fallback for Android
`redirect_ios`	Push settings	Store / app fallback for iOS
`redirect_web`	Push settings	Web fallback

redirect_* keys are omitted when the corresponding setting is empty. link is a Masivo short URL when one was generated for that send. Two fallbacks send the template destination URL instead:

Journey: the node has no short URL mapped yet
Test: the send is not tied to a stored push template

The host is never app.masivo.ai. It is the first custom domain in Links settings (for example https://links.example.com/l/AbCdEf).

Test send

Dashboard Send test from a push template:

{
  "notificationId": "test",
  "accountId": "00000000-0000-4000-8000-000000000001",
  "link": "https://links.example.com/l/AbCdEf",
  "redirect_android": "https://play.google.com/store/apps/details?id=com.example",
  "redirect_ios": "https://apps.apple.com/app/id123456789",
  "redirect_web": "https://example.com"
}

No customerId. If the test is not tied to a stored template, link is the template destination URL instead of a short URL.

Journey send

A Send push notification action on a journey:

{
  "customerId": "user_abc123",
  "accountId": "00000000-0000-4000-8000-000000000001",
  "link": "https://links.example.com/l/XyZ123",
  "redirect_android": "https://play.google.com/store/apps/details?id=com.example",
  "redirect_ios": "https://apps.apple.com/app/id123456789",
  "redirect_web": "https://example.com"
}

No notificationId. If the journey node already has short URLs, link is that short URL. Otherwise link is the template destination URL.

Scheduled audience send

Schedule from a push template to an audience:

{
  "notificationId": "11111111-1111-4111-8111-111111111111",
  "accountId": "00000000-0000-4000-8000-000000000001",
  "link": "https://links.example.com/l/AbCdEf"
}

notificationId is the delivery history id. No customerId on topic or per-device audience payloads.

Manual API send

POST /push/customers/{id}/send returns { data: { sent: true, customer_id, push_template_id } }. The device still receives this data map:

{
  "notificationId": "manual",
  "accountId": "00000000-0000-4000-8000-000000000001",
  "customerId": "user_abc123",
  "link": "https://links.example.com/l/AbCdEf"
}

Compare origins

Origin	`notificationId`	`customerId`
Dashboard test	`"test"`	omitted
Journey action	omitted	customer id
Scheduled audience	delivery history id	omitted
Manual API send	`"manual"`	customer id

Handle notification opens

const data = remoteMessage.data ?? {};
const link = typeof data.link === "string" ? data.link : null;
if (link) {
  await Linking.openURL(link);
}

await masivo.push.trackNotificationOpened({
  type: "PUSH_OPENED",
  customer_id: data.customerId ?? currentCustomerId,
  brand_id: brandId,
  notification_data: data
});

On a test send, data.customerId is missing — use the signed-in customer id.

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

FCM data payload

Data keys

Test send

Journey send

Scheduled audience send

Manual API send

Compare origins

Handle notification opens

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

​FCM data payload

​Data keys

​Test send

​Journey send

​Scheduled audience send

​Manual API send

​Compare origins

​Handle notification opens

​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

FCM data payload

Data keys

Test send

Journey send

Scheduled audience send

Manual API send

Compare origins

Handle notification opens

Best practices