Manage Topic Subscriptions
You can subscribe a client app to a topic from either the server or the client:
On the server, using theFirebase Admin SDK.
On the client, using the client-side API within your app.
Manage topic subscriptions using the Admin SDK
TheFirebase Admin SDKallows you to perform basictopic management tasks from the server side. Given their registrationtoken(s), you can subscribe and unsubscribe client app instances in bulk usingserver logic.
You can subscribe client app instances to any existing topic, oryou can create a new topic. When you use the API to subscribe a client appto a new topic (one that does not already exist for your Firebase project),a new topic of that name is created in FCM and any client can subsequentlysubscribe to it.
Important: To use theFirebase Admin SDK, you must first follow the steps inAdd the Firebase Admin SDK to your Server to initializethe SDK.You can pass a list of registration tokens to theFirebase Admin SDKsubscription method to subscribe the corresponding devices to a topic:
Node.js
// These registration tokens come from the client FCM SDKs.constregistrationTokens=['YOUR_REGISTRATION_TOKEN_1',// ...'YOUR_REGISTRATION_TOKEN_n'];// Subscribe the devices corresponding to the registration tokens to the// topic.getMessaging().subscribeToTopic(registrationTokens,topic).then((response)=>{// See the MessagingTopicManagementResponse reference documentation// for the contents of response.console.log('Successfully subscribed to topic:',response);}).catch((error)=>{console.log('Error subscribing to topic:',error);});Java
// These registration tokens come from the client FCM SDKs.List<String>registrationTokens=Arrays.asList("YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n");// Subscribe the devices corresponding to the registration tokens to the// topic.TopicManagementResponseresponse=FirebaseMessaging.getInstance().subscribeToTopic(registrationTokens,topic);// See the TopicManagementResponse reference documentation// for the contents of response.System.out.println(response.getSuccessCount()+" tokens were subscribed successfully");Python
# These registration tokens come from the client FCM SDKs.registration_tokens=['YOUR_REGISTRATION_TOKEN_1',# ...'YOUR_REGISTRATION_TOKEN_n',]# Subscribe the devices corresponding to the registration tokens to the# topic.response=messaging.subscribe_to_topic(registration_tokens,topic)# See the TopicManagementResponse reference documentation# for the contents of response.print(response.success_count,'tokens were subscribed successfully')Go
// These registration tokens come from the client FCM SDKs.registrationTokens:=[]string{"YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n",}// Subscribe the devices corresponding to the registration tokens to the// topic.response,err:=client.SubscribeToTopic(ctx,registrationTokens,topic)iferr!=nil{log.Fatalln(err)}// See the TopicManagementResponse reference documentation// for the contents of response.fmt.Println(response.SuccessCount,"tokens were subscribed successfully")C#
// These registration tokens come from the client FCM SDKs.varregistrationTokens=newList<string>(){"YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n",};// Subscribe the devices corresponding to the registration tokens to the// topicvarresponse=awaitFirebaseMessaging.DefaultInstance.SubscribeToTopicAsync(registrationTokens,topic);// See the TopicManagementResponse reference documentation// for the contents of response.Console.WriteLine($"{response.SuccessCount} tokens were subscribed successfully");TheFirebase Admin SDK also lets you unsubscribe devices from a topicby passing registration tokens to the appropriatemethod:
Node.js
// These registration tokens come from the client FCM SDKs.constregistrationTokens=['YOUR_REGISTRATION_TOKEN_1',// ...'YOUR_REGISTRATION_TOKEN_n'];// Unsubscribe the devices corresponding to the registration tokens from// the topic.getMessaging().unsubscribeFromTopic(registrationTokens,topic).then((response)=>{// See the MessagingTopicManagementResponse reference documentation// for the contents of response.console.log('Successfully unsubscribed from topic:',response);}).catch((error)=>{console.log('Error unsubscribing from topic:',error);});Java
// These registration tokens come from the client FCM SDKs.List<String>registrationTokens=Arrays.asList("YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n");// Unsubscribe the devices corresponding to the registration tokens from// the topic.TopicManagementResponseresponse=FirebaseMessaging.getInstance().unsubscribeFromTopic(registrationTokens,topic);// See the TopicManagementResponse reference documentation// for the contents of response.System.out.println(response.getSuccessCount()+" tokens were unsubscribed successfully");Python
# These registration tokens come from the client FCM SDKs.registration_tokens=['YOUR_REGISTRATION_TOKEN_1',# ...'YOUR_REGISTRATION_TOKEN_n',]# Unubscribe the devices corresponding to the registration tokens from the# topic.response=messaging.unsubscribe_from_topic(registration_tokens,topic)# See the TopicManagementResponse reference documentation# for the contents of response.print(response.success_count,'tokens were unsubscribed successfully')Go
// These registration tokens come from the client FCM SDKs.registrationTokens:=[]string{"YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n",}// Unsubscribe the devices corresponding to the registration tokens from// the topic.response,err:=client.UnsubscribeFromTopic(ctx,registrationTokens,topic)iferr!=nil{log.Fatalln(err)}// See the TopicManagementResponse reference documentation// for the contents of response.fmt.Println(response.SuccessCount,"tokens were unsubscribed successfully")C#
// These registration tokens come from the client FCM SDKs.varregistrationTokens=newList<string>(){"YOUR_REGISTRATION_TOKEN_1",// ..."YOUR_REGISTRATION_TOKEN_n",};// Unsubscribe the devices corresponding to the registration tokens from the// topicvarresponse=awaitFirebaseMessaging.DefaultInstance.UnsubscribeFromTopicAsync(registrationTokens,topic);// See the TopicManagementResponse reference documentation// for the contents of response.Console.WriteLine($"{response.SuccessCount} tokens were unsubscribed successfully");messaging/invalid-argument error.ThesubscribeToTopic() andunsubscribeFromTopic() methods results in anobject containing the response fromFCM. The return type has the sameformat regardless of the number of registration tokens specified in therequest.
In case of an error (authentication failures, invalid token or topic etc.)these methods result in an error.For a full list of error codes, including descriptionsand resolution steps, seeFirebase Admin SDK Errors.
Manage topic subscriptions from your client app
Client app instances can also be subscribed or unsubscribed to topics directlyfrom your app through the Firebase SDKs. Note thatFCM retries incase of initial failures to ensure the subscription is successful.
Choose your platform:
Android
Client apps can subscribe to any existing topic, or they can create a newtopic. When a client app subscribes to a new topic name (one that doesnot already exist for your Firebase project), a new topic of that name iscreated inFCM and any client can subsequently subscribe to it.
To subscribe to a topic, the client app callsFirebase Cloud MessagingsubscribeToTopic() with theFCM topic name. This method returns aTask, which can be used by a completion listener to determine whether the subscription succeeded:
Kotlin
Firebase.messaging.subscribeToTopic("weather").addOnCompleteListener{task->varmsg="Subscribed"if(!task.isSuccessful){msg="Subscribe failed"}Log.d(TAG,msg)Toast.makeText(baseContext,msg,Toast.LENGTH_SHORT).show()}
Java
FirebaseMessaging.getInstance().subscribeToTopic("weather").addOnCompleteListener(newOnCompleteListener<Void>(){@OverridepublicvoidonComplete(@NonNullTask<Void>task){Stringmsg="Subscribed";if(!task.isSuccessful()){msg="Subscribe failed";}Log.d(TAG,msg);Toast.makeText(MainActivity.this,msg,Toast.LENGTH_SHORT).show();}});
To unsubscribe, the client app callsFirebase Cloud MessagingunsubscribeFromTopic() with the topic name.
iOS
Client apps can subscribe to any existing topic, or they can create a newtopic. When a client app subscribes to a new topic name (one that doesnot already exist for your Firebase project), a new topic of that name iscreated inFCM and any client can subsequently subscribe to it.
To subscribe to a topic, call the subscription method from your application's main thread (FCM is not thread-safe).If the subscription request fails initially,FCM retries automatically.For cases where the subscription cannot be completed,the subscription throws an error that you can catchin a completion handler as shown:
Swift
Messaging.messaging().subscribe(toTopic: "weather") { error in print("Subscribed to weather topic")}Objective-C
[[FIRMessagingmessaging]subscribeToTopic:@"weather"completion:^(NSError*_Nullableerror){NSLog(@"Subscribed to weather topic");}];
This call makes anasynchronous request to theFCM backend and subscribes the client tothe given topic. Before callingsubscribeToTopic:topic, make sure that theclient app instance has already received a registration token via the callbackdidReceiveRegistrationToken.
Each time the app starts,FCM makes sure that all requested topics have been subscribed. To unsubscribe, callunsubscribeFromTopic:topic, andFCM unsubscribes from the topic in the background.
C++
To subscribe to a topic, call::firebase::messaging::Subscribe from your application. This makes an asynchronous request to theFCM backend and subscribes the client to the given topic.
::firebase::messaging::Subscribe("example");
If the subscription request fails initially,FCM retries until it can subscribe to the topic successfully. Each time the app starts,FCM makes sure that all requested topics have been subscribed.
To unsubscribe, call::firebase::messaging::Unsubscribe, andFCM unsubscribes from the topic in the background.
Unity
To subscribe to a topic, callFirebase.Messaging.FirebaseMessaging.Subscribe from your application. This makes an asynchronous request to theFCM backend and subscribes the client to the given topic.
Firebase.Messaging.FirebaseMessaging.Subscribe("/topics/example");
If the subscription request fails initially,FCM retries until it can subscribe to the topic successfully. Each time the app starts,FCM makes sure that all requested topics have been subscribed.
To unsubscribe, callFirebase.Messaging.FirebaseMessaging.Unsubscribe, andFCM unsubscribes from the topic in the background.
Legacy Server-Side Topic Management (Deprecated)
Warning: The legacy Instance ID service consists of REST APIs to manage topic subscriptions,including adding and removing individual tokens, and batch operations. TheseAPIs are deprecated and are no longer recommended for new development.To understand what Instance IDs are, visit theInstance ID page. For details onthe deprecated endpoints, see theInstance ID API References.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-18 UTC.