Sending Push Notifications

Send push notifications to your users' devices using push templates and registered device tokens.

Prerequisites

Before sending, make sure you have:

• Configured FCM under Push Providers
• Created a Push Template
• Registered the target user's device token (see Integration Guide below)

Integration Guide

Push notifications follow the same pattern as email and messages in MessagePipe. Your backend is the only thing that ever calls MessagePipe directly. Your mobile app never touches MessagePipe.

The flow:

Mobile app
  → sends FCM device token to YOUR backend
    → YOUR backend calls MessagePipe /push/register-device

When an event happens (e.g. payment, transfer):
  YOUR backend → calls MessagePipe /push/send
    → MessagePipe finds the user's device tokens
      → sends via FCM using your stored credentials
        → notification appears on device

This is identical to how email and messages work. Your app provides FCM credentials, MessagePipe stores them and handles delivery on your behalf. Your mobile app never knows MessagePipe exists.

Step 1: Receive the Device Token in Your Backend

Add an endpoint to your backend that receives the FCM token from your mobile app and forwards it to MessagePipe:

// Node.js / Express example
app.post("/users/register-device", authenticateToken, async (req, res) => {
  const userId = req.user.userId;
  const { deviceToken, platform } = req.body;

  await axios.post(
    `${process.env.MESSAGEPIPE_URL}/push/register-device`,
    { userId, deviceToken, provider: "fcm", platform },
    {
      headers: {
        "x-api-key": process.env.MESSAGEPIPE_API_KEY,
        "Content-Type": "application/json",
      },
    },
  );

  res.json({ message: "Device registered successfully" });
});

Step 2: Call Register-Device from Your Mobile App

In your mobile app, get the FCM token and send it to your own backend. Not to MessagePipe directly:

// React Native example
import * as Notifications from "expo-notifications";
import * as Device from "expo-device";
import { Platform } from "react-native";

const registerForPushNotifications = async () => {
  if (!Device.isDevice) return;

  const { status } = await Notifications.requestPermissionsAsync();
  if (status !== "granted") return;

  const token = await Notifications.getDevicePushTokenAsync();

  // Send to your backend
  await axios.post(
    `${YOUR_BACKEND_URL}/users/register-device`,
    { deviceToken: token.data, platform: Platform.OS },
    { headers: { Authorization: `Bearer ${userAuthToken}` } },
  );
};

It is advised to call this on every app launch while the user is authenticated. FCM tokens can change after reinstalls or when FCM rotates them silently. The register-device endpoint is idempotent, so calling it repeatedly is safe.

Step 3: Send Notifications from Your Backend

When an event occurs in your app, call MessagePipe from your backend:

// Send a push notification when a transfer is received
const notifyUser = async (recipientUserId, transferAmount) => {
  await axios.post(
    `${process.env.MESSAGEPIPE_URL}/push/send`,
    {
      userId: recipientUserId,
      templateId: process.env.TRANSFER_NOTIFICATION_TEMPLATE_ID,
      variables: { amount: transferAmount },
    },
    {
      headers: {
        "x-api-key": process.env.MESSAGEPIPE_API_KEY,
        "Content-Type": "application/json",
      },
    },
  );
};

Register a Device Token

POST /push/register-device?projectId={projectId}
Content-Type: application/json
x-api-key: your-api-key

{
  "userId": "user-123",
  "deviceToken": "fcm-device-token-here",
  "provider": "fcm",
  "platform": "android"
}

Field	Required	Description
userId	Yes	Your customer's user ID
deviceToken	Yes	The FCM device token from the client SDK
provider	Yes	Push provider: currently fcm
platform	Yes	android, ios or web

Rate limit: 60 requests/minute.

Get a User's Registered Devices

GET /push/devices/{userId}?projectId={projectId}
Authorization: Bearer your-jwt-token

Send to a Single User

POST /push/send?projectId={projectId}
Content-Type: application/json
x-api-key: your-api-key

{
  "userId": "user-123",
  "templateId": "template-uuid",
  "variables": {
    "name": "testuser"
  },
  "imageUrl": "https://example.com/image.png",
  "data": {
    "screen": "order-details",
    "orderId": "ORD-456"
  }
}

Field	Required	Description
userId	Yes	Your customer's user ID
templateId	Yes	UUID of the push template to use
variables	No	Variables to inject into the template
imageUrl	No	Optional image to display in the notification
data	No	Key-value payload sent to the app (e.g. for deep linking)

Rate limit: 100 requests/minute.

Send to Multiple Users

POST /push/send-bulk?projectId={projectId}
Content-Type: application/json
x-api-key: your-api-key

{
  "userIds": ["user-123", "user-456", "user-789"],
  "templateId": "template-uuid",
  "variables": {
    "promoCode": "SAVE20"
  },
  "data": {
    "screen": "promotions"
  }
}

Maximum of 500 users per bulk request.

Rate limit: 10 requests/minute.

---

When using JWT authentication, pass projectId as a query parameter. With API key auth, it is automatically gotten from the key.