Push Channel Introduction

Learn how to send push notifications with Novu using external providers like FCM, Expo etc.

Push notifications are short, targeted messages delivered to a user’s device or browser, often through mobile apps or websites. They serve as a powerful communication tool, offering real-time updates, reminders, and personalized content. Push notifications can range from news alerts and social media updates to promotional offers and important app notifications.

These messages are designed to engage users and keep them informed about relevant events or activities, even when they are not actively using an app or browsing a website. They play a crucial role in user engagement and retention for businesses and organizations, as they can re-engage users and prompt them to take specific actions.

Novu can be used to deliver push notifications to your customers devices using a unified delivery API. Both Mobile and Web push notifications are supported.

Using push channel with Novu

To send a push notification to subscribers (users) using Novu:

• Add a push channel provider in integration store
• Add push channel as a step in existing or new workflow.
• Add static or dynamic content using variables in push step fields
• Store provider specific device tokens/identifiers in subscriber profile. Read provider specific documentation on how to obtain and store device tokens.
• Make sure all provider specific steps are configured properly before triggering workflow. Read provider related documentation for all required steps.
• Trigger the workflow.

Supported providers

• Firebase Cloud Messaging (FCM)
• Expo Push
• Apple Push Notification Service
• OneSignal
• Pushpad
• Push Webhook

Novu supports multiple active providers for push channel.

Are we missing a provider you'd like to use for PUSH channel? Please consider adding a new feature request on github or help us upvoting the existing ones on our public roadmap

Managing push device tokens

To send push notifications to subscribers, you need to store device tokens or identifiers in subscriber profiles. These tokens are unique identifiers that help push notification providers deliver messages to the correct devices. Each provider has its own method for obtaining and storing device tokens.

Novu offers to ways of keeping your device tokens in sync with subscriber profiles:

• Just-in-time: Pass device tokens in the payload when triggering a workflow. Novu will automatically update subscriber profiles with the new device tokens.
• Manual: Update subscriber profiles with device tokens using the Novu Set Credentials API.

Just-in-time

When triggering a workflow, you can pass the channels array on the subscriber object with the device tokens for the push provider of your choice. Here is an example with fcm:

novu.trigger("workflow-id", {
  to: {
    subscriberId: "subscriber-id",
    channels: [
      {
        providerId: "fcm",
        credentials: {
          deviceTokens: ["token-1", "token-2"],
        },
      },
    ],
  },
  payload: {},
});

Manual

Use the Novu Set Credentials API to update subscriber profiles with device tokens. You can read more about the API in the API Reference or the FCM Example

Frequently Asked Questions

How to remove one device token from subscriber credentials?

To remove a device token from subscriber credentials, you need to get the current device tokens from subscriber credentials, remove all deviceTokens, remove the token you want to remove and then update the subscriber credentials with new device tokens.

• Node.js

import {
  Novu,
  PushProviderIdEnum
} from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

// fetch subscriber details
const subscriber = await novu.subscribers.get('subscriberId');

// get current device tokens from subscriber credentials for the provider
const currentDeviceTokens = subsciber.data.data.channels.find(
  // _integrationId can also be checked in place of providerId ;
  (channel) => channel.providerId === PushProviderIdEnum.FCM,
).credentials.deviceTokens;

// remove all device tokens
await this.novu.subscribers.setCredentials(
  'subscriberId',
  PushProviderIdEnum.FCM, {
    deviceTokens: []
  },
);

// remove the token you want to remove
const newDeviceTokens = currentDeviceTokens.filter(
  (token) => token !== 'token-to-be-removed',
);

// update subscriber credentials with new device tokens
await this.novu.subscribers.setCredentials(
  'subscriberId',
  PushProviderIdEnum.FCM, {
    deviceTokens: newDeviceTokens
  },
);