---
source_url: https://www.pubnub.com/docs/migration-guides/legacy-http-fcm
title: Migrate from legacy HTTP FCM to FCM HTTP v1
updated_at: 2026-09-30T07:20:08.000Z
---

# Migrate from legacy HTTP FCM to FCM HTTP v1

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Google retired the legacy Firebase Cloud Messaging (FCM) HTTP API, and [Mobile Push Notifications](https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview.md) moved Android push from that API to FCM HTTP v1. This guide moves a keyset still configured for legacy HTTP FCM, and still sending `pn_gcm` payloads, to FCM HTTP v1 and `pn_fcm`.

## Before you start

Confirm you have:

* Admin Portal access to the keyset that has **Mobile Push Notifications** enabled for Android.
* A Firebase service-account private key file (JSON) for the same Firebase project your app already uses. If you don't have one yet, generate it by following [Give PubNub your Firebase credentials](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-android.md#give-pubnub-your-firebase-credentials).

## Migrate with an AI coding assistant

If you use an AI coding assistant, paste this prompt into it to rewrite your push payloads. The prompt makes the assistant read this guide, list every `pn_gcm` payload first, and ask you to confirm the keyset credential change before it ships new payloads. Do the Admin Portal steps in [Update your keyset's FCM credentials](#update-your-keysets-fcm-credentials) yourself.

```text
Migrate this codebase's PubNub Android push payloads from legacy HTTP FCM and
pn_gcm to FCM HTTP v1 and pn_fcm.

1. Read the migration guide first:
   https://www.pubnub.com/docs/migration-guides/legacy-http-fcm.md
   If the PubNub MCP server is connected, you can call get_general_migration_guide
   instead. Where the guide and your own knowledge of PubNub disagree, follow the
   guide and tell me.
2. Before you edit anything, list every place that builds or publishes a pn_gcm
   payload. Then show me a plan and wait for my approval.
3. Before you ship payload changes, ask me to confirm that I replaced the Firebase
   Server Key with the service-account private key file on the keyset in the
   Admin Portal. You can't do that step.
4. Rewrite each pn_gcm payload as pn_fcm. The two structures differ, so don't
   rename the key and reuse its contents. Move Android-specific fields, such as
   content_available and sound, under pn_fcm.android.
5. Make every value inside data a string. pn_fcm rejects numbers, booleans, and
   nested objects there.
6. Don't include topic. PubNub sets it and overwrites any value you supply.
7. If a pn_gcm payload stops producing a notification, rewrite it as pn_fcm.
   Don't adjust the pn_gcm payload further.
8. Make one small change at a time. After each change, run the build and tests
   and show me the output.
9. Never add the Firebase private key file, the PubNub secret key, or any other
   credential to the repository or to client code.
10. When you finish, list every file you changed and the steps left for me.
```

## Update your keyset's FCM credentials

1. Open [Admin Portal](https://admin.pubnub.com) and select the app and keyset that sends Android push.
2. Find the **Mobile Push Notifications** section.
3. Where you previously pasted a Firebase **Server Key**, switch to **Private key file** and upload the JSON key file.
4. Save the keyset.

## Update your push payload

Publish messages with a `pn_fcm` payload instead of `pn_gcm`. The two objects use different structures, so rewrite the JSON your app publishes rather than only renaming the key.

```json
{
  "pn_debug": true,
  "pn_fcm": {
    "notification": {
      "body": "common-body"
    },
    "android": {
      "collapse_key": "group",
      "data": {
        "age": "10"
      },
      "ttl": "30s",
      "notification": {
        "sound": "default"
      }
    }
  }
}
```

Legacy `pn_gcm` payloads put `content_available` and `sound` directly under `notification`. Move Android-specific fields under `pn_fcm.android` instead of renaming `pn_gcm` and reusing its contents.

Two constraints apply to every `pn_fcm` payload:

* Every value inside `data` must be a string. `pn_fcm` rejects numbers, booleans, and nested objects there.
* Don't include `topic`. PubNub sets it automatically in the `pn_fcm` payload and overwrites any value you supply.

[Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md) and [Send push notifications on Android](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-android.md) cover only the `pn_fcm` shape. If a `pn_gcm` payload you send today stops producing a notification, rewrite it as `pn_fcm` using the mapping above rather than adjusting the legacy payload further.

## Related tasks

* [Send push notifications on Android](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-android.md). Register a device and send a first `pn_fcm` push end to end.
* [Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md). Fix a `pn_fcm` push that PubNub delivers but that doesn't display or behave as expected.
* [Mobile push notifications](https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview.md). The delivery model behind APNs and FCM push, including per-keyset credentials.
* [Debug push notification messages](https://www.pubnub.com/docs/integrations/mobile-push-notifications/debug-push-notification-messages.md). Trace a push failure on the `-pndebug` channel.

Last updated at: 2026-09-30T07:20:08.000Z