Migrate from legacy FCM to FCM HTTP v1
31 July by Bartosz Górka

Migrate from Legacy FCM to new FCM HTTP v1

In this article, I will show you how easy it is to migrate from Legacy Firebase Cloud Messaging to the new FCM HTTP v1 service. Our goal is to archive communication between Server and FCM using steps presented below.

Attention, it’s important!
To be able to use the presented code, you must have an active account at Firebase Service - project registration is free.


Migrating to the new version of any API takes some time, so it’s important to consider what we can gain. In this case, the old FCM API can still be used, it is also simpler in configuration. So why is it worth switching to the new version?

Up to date with changes

FCM HTTP v1 service is dynamically developed to provide functionalities that appear on individual platforms. I was impelled by the wonderfully implemented grouping of messages with unlimited collapse keys. In this version it works without any issues (in Legacy API, there were problems for both Android and iOS).

Better authorization, better security

Legacy FCM uses tokens generated once for the entire lifetime of the application. If such token was made available to third parties, they could use it and compromise our application. In the new API, the token is valid only for one hour. After this time, you have to generate a new one. This increases the security, but also makes it more difficult to use the FCM API because you have to handle the dynamic changes of the tokens.

More convenient creation of messages for individual platforms

In Legacy FCM we do not have the possibility to send different messages to different platforms in a single request (without distinguishing tokens, treating the registered devices equally). This means that we probably send more data than the recipient actually needs - which drops responsibility on mobile application developers.

I believe that presented benefits, especially being up to date with changes and the control over messages sent, made the article worth reading and that I will convience you to migrate to the new service.

Let’s get started!

Step I

First, we need to log in to our account in Firebase Console and in the Project settings go to the Service Accounts tab. After selecting the Generate New Private Key action, we will get a JSON file with the necessary data.

Attention, it’s important!
You can also use another service account, but must set the Editor or Owner permission.

From the above file, two fields are interesting for us - client_email that is information about our client (my firebase_fcm_issuer) and private_key which will be used to sign the generated JWT token (firebase_fcm_private_key).

Step II

Activate Firebase Cloud Messaging API to be able to use the new version of FCM.

Step III

Using the results obtained in Step I, we can prepare an authorization module that will help us to generate the necessary Access Token.

I’ve used the external library Joken and Tesla. Also, to make testing this module easier (generated JWT token), I’ve split the generation step from using the JWT token in Google APIs OAuth2, which will give us the Access Token necessary for authorization.

After preparing the modules and setting the data with the service account, we can check how our code works. If we have done everything correctly, we should get an access token with a similar structure: ya29.c.Elo … 600

Step IV

Finally, it’s time for send push notification using the new FCM HTTP v1 service!
So far we have been sending a POST request to https://fcm.googleapis.com/fcm/send to send notifications. In the new version, we need to change this URL to https://fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send where we have to insert a project ID (you can also get PROJECT_ID from the service account file from the Step I).

We will need authorization settings. The most convenient is to use the Tesla client and prepare a module similar to the one below

We can also use the following module to send push notification

The fields that are available in the message, their description and more details can be obtained by reading the documentation at the Docs Website

Additional information

The new service allows you to perform tests without delivering a push notification to the receiver. This is important when you change implementation on production servers and do not want to send actual push notifications, but only want to check if the changes are correct. By adding the field validate_only with the value true next to message, you can check if the code works, without actually sending a notification to the client (more details at Docs Website) .

Moreover, the FCM checks the validity of the keys used in the message. Trying to send an invalid key, will result in an error that helps us fix our mistake.


I hope that the solutions presented were worth reading and succeeded. I am waiting for your suggestions and comments.

You can find me on Medium, GitHub or Twitter

Let's work together!