Push Providers Integration

Push providers are the services that deliver notifications your subscribers' devices, which can be delivered through mobile, desktop, or web. Each provider must be set up individually in the Novu dashboard.

Novu provides a unified integration layer that connects your workflows to push providers. Once your push provider is configured, Novu automatically handles message delivery, routing each notification through the correct provider without requiring extra setup.

You can also manage multiple integrations even for the same provider in one place, giving you full flexibility and centralized control over your push notifications.

Key features

• Multi-provider support: Integrate with providers like Firebase Cloud Messaging (FCM), OneSignal, or Apple Push Notification Service (APNS).
• Unified delivery: Streamline your push notifications with a single API for mobile and web platforms.
• Device management: Keep subscriber device tokens in sync using just-in-time or manual updates.

How push works in Novu

Here is the step-by-step process for sending a push notification with Novu:

Managing push device tokens

To send push notifications, each subscriber must have one or more device tokens or identifiers associated with their profile.

These tokens are unique identifiers that help push notification providers deliver messages to the correct devices. Each provider has its own method for obtaining device tokens, refer to your provider's guide to learn how to obtain the device tokens.

Add push device tokens

Novu offers two ways of adding device tokens to a subscriber's profile:

• Update device tokens just in time.
• Add device tokens manually.

Add device tokens during just in time

You can pass the device tokens in the channels array of the subscriber object when triggering a workflow. Novu automatically updates the subscriber's profile with these tokens before sending the message. Here is an example with FCM:

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Use serverURL for EU region
  // serverURL: "https://eu.api.novu.co",
});
 
await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
    channels: [
      {
        providerId: ChatOrPushProviderEnum.Fcm,
        credentials: {
          deviceTokens: ["token-1", "token-2"],
        }
      },
    ],
  },
  payload: {},
});

Add device tokens manually

You can manually store or update device tokens for a subscriber using the Update provider credentials API.

This method is useful when you manage device registration outside of your workflow triggers, for example, after a user logs in.

import { Novu } from "@novu/api";
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",});
 
async function run() {
  const result = await novu.subscribers.credentials.update({
    providerId: ChatOrPushProviderEnum.Fcm,
    credentials: {
      deviceTokens: [
        "token1",
        "token2",
      ],
    },
  }, "subscriberId");
}
run();

Add device tokens for multiple integrations

Novu supports multiple active integrations per provider for the push channel. For example, you can have more than one active FCM integration at a time, one for your customer app and one for your internal app.

By default, device tokens are stored for the most recently created integration. To store device tokens for a specific integration, you must use the integrationIdentifier field. This is the identifier for the integration, which you can find in the Novu dashboard.

import { Novu } from "@novu/api";
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",});
 
async function run() {
  const result = await novu.subscribers.credentials.update({
    providerId: ChatOrPushProviderEnum.Fcm,
    // Use integrationIdentifier to store device tokens for a specific integration
    integrationIdentifier: "fcm-MnGLxp8uy",
    credentials: {
      deviceTokens: [
        "token1",
        "token2",
      ],
    },
  }, "subscriberId");
}
run();

Remove device tokens

To remove device token(s) from subscriber credentials, follow this process:

When a subscriber logs out of a device, remove that device token from the subscriber's credentials. This prevents another subscriber who may log in to the same device from receiving notifications meant for the previous subscriber.

Remove a specific token

To remove device tokens from subscriber credentials, follow this process:

1. Fetch the subscriber's current token list.
2. Filter out the token you want to remove.
3. Update the subscriber with the new, filtered list.

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});
 
const subscriberId = "subscriberId";
const providerId = ChatOrPushProviderEnum.Fcm;
 
// 1. Fetch current credentials
const { data: subscriber } = await novu.subscribers.get(subscriberId);
const currentTokens = subscriber.credentials[providerId]?.deviceTokens || [];
 
// 2. Remove the specific token
const filteredTokens = currentTokens.filter(token => token !== "token_to_remove");
 
// 3. Update subscriber
await novu.subscribers.credentials.update(
  {
    providerId,
    credentials: {
      deviceTokens: filteredTokens,
    },
  },
  subscriberId
);

Remove all tokens

To remove all device tokens for a provider, or for a specific integration, update the credentials with an empty array.

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";
 
const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});
 
await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.Fcm,
    credentials: {
      deviceTokens: [],
    },
  },
  "subscriberId"
);

Supported providers

Novu supports the following providers: