Manage Topic Subscriptions

The Firebase Admin Node.js SDK provides an API for managing device subscriptions to Firebase Cloud Messaging (FCM) topics. The Admin FCM API gives you the ability to programmatically subscribe to and unsubscribe from topics.

Before you begin

To use the Admin FCM API, you must first follow the steps in Add the Firebase Admin SDK to your Server to initialize the SDK.

Subscribe to a topic

The Admin FCM API allows you to subscribe a device to a topic by providing a registration token for the device to subscribe. Registration tokens are strings generated by the client FCM SDKs for each end-user client app instance.

Each of the Firebase client SDKs are able to generate these registration tokens: iOS, Android, Web, C++, and Unity.

You can pass one of these registration tokens to the subscribeToTopic() method to subscribe that device to a topic:

// This registration token comes from the client FCM SDKs.
var registrationToken = "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...";

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// Subscribe the device corresponding to the registration token to the
// topic.
admin.messaging().subscribeToTopic(registrationToken, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log("Successfully subscribed to topic:", response);
  })
  .catch(function(error) {
    console.log("Error subscribing to topic:", error);
  });

The subscribeToTopic() method can also subscribe multiple devices in a single call by passing an array of registration tokens instead of just a single registration token:

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  // ...
  "ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf..."
];

// Subscribe the devices corresponding to the registration tokens to the
// topic.
admin.messaging().subscribeToTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log("Successfully subscribed to topic:", response);
  })
  .catch(function(error) {
    console.log("Error subscribing to topic:", error);
  });

The subscribeToTopic() method returns a promise that is resolved with a MessagingTopicManagementResponse object containing the response from FCM. The return type has the same format when passing a single registration token or an array of registration tokens.

Some cases such as an authentication error or rate limiting cause the request to fail. In these cases, the promise returned by subscribeToTopic() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin FCM API Errors.

Unsubscribe from a topic

The Admin FCM API also allows you to unsubscribe a device from a topic by passing a registration tokens to the unsubscribeFromTopic() method:

// This registration token comes from the client FCM SDKs.
var registrationToken = "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...";

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// Unsubscribe the device corresponding to the registration token from
// the topic.
admin.messaging().unsubscribeFromTopic(registrationToken, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log("Successfully unsubscribed from topic:", response);
  })
  .catch(function(error) {
    console.log("Error unsubscribing from topic:", error);
  });

The unsubscribeFromTopic() method can also unsubscribe multiple devices in a single call by passing an array of registration tokens instead of just a single registration token:

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  // ...
  "ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf..."
];

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
admin.messaging().unsubscribeFromTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log("Successfully unsubscribed from topic:", response);
  })
  .catch(function(error) {
    console.log("Error unsubscribing from topic:", error);
  });

The unsubscribeFromTopic() method returns a promise that is resolved with a MessagingTopicManagementResponse object containing the response from FCM. The return type has the same format when passing a single registration token or an array of registration tokens.

Some cases such as an authentication error or rate limiting cause the request to fail. In these cases, the promise returned by unsubscribeFromTopic() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin FCM API Errors.