Send push with Firebase Cloud Messaging through Courier

Prerequisites

A Firebase project
A service account private key from that project
For iOS, an APNs key uploaded to Firebase

Setup

Configure FCM provider

Generate a private key

In your Firebase Project, go to “Project Settings” > “Service Accounts” and generate a new private key.

Add the key to Courier

Copy the contents of the downloaded private key JSON file and paste it into Service Account JSON in the .

Review the remaining settings

Apply Recommended Courier Mobile SDK Formatting, on by default. It ships the message as a data payload rather than notification, so Android wakes in the background and your own notification style applies. That background wake is also what reports the delivery back to Courier. It attaches an APNs override for Courier’s too, so an iOS device receiving through FCM still tracks delivery. See .

FCM provider configuration showing the Apply Recommended Courier Mobile SDK Formatting toggle — The Courier FCM provider configuration with the Apply Recommended Courier Mobile SDK Formatting toggle enabled.

Bundle ID and Filter By Bundle ID, off by default. Together they restrict a send to tokens whose device.app_id matches, so a user with two app installs only gets it on the right one.

Install the provider

Click “Install Provider” or “Save” to complete the configuration.

Enable iOS support (if required)

Integrate Firebase into your iOS project

Integrate Firebase into your iOS project.

Select your iOS project in Cloud Messaging

In your Firebase project settings, go to “Cloud Messaging” and select your iOS project under “Apple app configuration”.

Create an APNs key

Create a new key in your Apple Developer Account with “Apple Push Notifications Service (APNs)” enabled.

Upload the .p8 file to Firebase

Download the generated .p8 file and upload it to your Firebase project settings under “Apple apps” > your app > “APNs Authentication Key”.

Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. covers the model. FCM addresses the device by registration token, so the profile you send to needs a firebaseToken. Store the token once with , which merges into the profile and creates it if it does not exist:

One device
Several devices

A single registration token, as a string.

const profile = await client.profiles.create('user_123', {
  profile: {
    firebaseToken: 'YOUR_FCM_TOKEN',
  },
});

profile = client.profiles.create(
    user_id="user_123",
    profile={
        "firebaseToken": "YOUR_FCM_TOKEN",
    },
)

curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "firebaseToken": "YOUR_FCM_TOKEN"
    }
  }'

profile = courier.profiles.create(
  "user_123",
  profile: {
    firebaseToken: "YOUR_FCM_TOKEN"
  }
)

profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"firebaseToken": "YOUR_FCM_TOKEN",
		},
	},
)

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("firebaseToken", JsonValue.from("YOUR_FCM_TOKEN"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);

$profile = $client->profiles->create('user_123', profile: [
  'firebaseToken' => 'YOUR_FCM_TOKEN',
]);

ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "firebaseToken", JsonSerializer.SerializeToElement("YOUR_FCM_TOKEN") },
    },
};
var profile = await client.Profiles.Create(parameters);

courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"firebaseToken":"YOUR_FCM_TOKEN"}'

With Courier MCP, save the FCM token YOUR_FCM_TOKEN on user_123.

An array reaches every device that user signs in on.

const profile = await client.profiles.create('user_123', {
  profile: {
    firebaseToken: [
      'FCM_TOKEN_ONE',
      'FCM_TOKEN_TWO',
    ],
  },
});

profile = client.profiles.create(
    user_id="user_123",
    profile={
        "firebaseToken": [
            "FCM_TOKEN_ONE",
            "FCM_TOKEN_TWO",
        ],
    },
)

curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "firebaseToken": [
        "FCM_TOKEN_ONE",
        "FCM_TOKEN_TWO"
      ]
    }
  }'

profile = courier.profiles.create(
  "user_123",
  profile: {
    firebaseToken: ["FCM_TOKEN_ONE", "FCM_TOKEN_TWO"]
  }
)

profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"firebaseToken": []any{"FCM_TOKEN_ONE", "FCM_TOKEN_TWO"},
		},
	},
)

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("firebaseToken", JsonValue.from(java.util.List.of("FCM_TOKEN_ONE", "FCM_TOKEN_TWO")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);

$profile = $client->profiles->create('user_123', profile: [
  'firebaseToken' => ['FCM_TOKEN_ONE', 'FCM_TOKEN_TWO'],
]);

ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "firebaseToken": [
            "FCM_TOKEN_ONE",
            "FCM_TOKEN_TWO"
          ]
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);

courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"firebaseToken":["FCM_TOKEN_ONE","FCM_TOKEN_TWO"]}'

With Courier MCP, save the FCM tokens FCM_TOKEN_ONE and FCM_TOKEN_TWO on user_123.

On Android the Courier SDK keeps that token current once you forward onNewToken to it. You send to a user_id and never put a token on a profile yourself. On iOS, FCM is a token you register and refresh, because the SDK’s own hook there is APNs. For a one-off with no stored profile, pass it inline instead: "to": { "firebaseToken": "YOUR_FCM_TOKEN" }.

Set up push notifications

Wire up the SDK, sync tokens, and send your first push.

Send by user id

The call in every language, and the rest of the profile object.

Send to a recipient

Send to user id
Send to a token

Courier reads firebaseToken off the saved profile, so preferences apply and the value can change without touching this code.

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, send my template to user_123 by email.

Pass it inline instead and nothing is stored. Swap this to object into the call on the other tab.

To address	Use
One device	`"to": { "firebaseToken": "YOUR_FCM_TOKEN" }`
Several devices	`"to": { "firebaseToken": ["FCM_TOKEN_ONE", "FCM_TOKEN_TWO"] }`
A user, and a specific device	`"to": { "user_id": "user_123", "firebaseToken": "YOUR_FCM_TOKEN" }`

Without a user_id, Courier logs the message under a synthetic anon_<hash> recipient and you lose:

Stored preferences and profile.
Managed token lookup, expiry, sign-out cleanup, and bundleId filtering.
Delivery and click events on that person’s history.

Put both a user_id and a token in to to supply your own and keep the user.

To pick among several tokens on one user, see .

const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      firebaseToken: "YOUR_FCM_TOKEN",
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

response = client.send.message(
    message={
        "to": {
            "firebaseToken": "YOUR_FCM_TOKEN",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "firebaseToken": "YOUR_FCM_TOKEN"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      firebaseToken: "YOUR_FCM_TOKEN"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"firebaseToken": "YOUR_FCM_TOKEN"}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("firebaseToken", JsonValue.from("YOUR_FCM_TOKEN"))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());

$response = $client->send->message(
  message: [
    'to' => [
      'firebaseToken' => 'YOUR_FCM_TOKEN',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"firebaseToken": "YOUR_FCM_TOKEN"}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"firebaseToken": "YOUR_FCM_TOKEN"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, send my template to the FCM token YOUR_FCM_TOKEN.

Overrides

covers the two levels and which one wins. lists the fields every push provider takes. An override changes the request Courier sends to FCM. Two paths cover most cases:

providers.firebase-fcm.override.body.data.YOUR_CUSTOM_KEY adds custom data, usually to open a screen on tap. Firebase requires data to be flat, and override values merge in raw, so every value must already be a string. See Firebase’s data field reference.
providers.firebase-fcm.override.body.apns applies iOS-specific values. See Apple’s remote notification guide.

providers.firebase-fcm.override.config replaces the integration’s own settings for a single send:

Key	What it replaces
`serviceAccountJSON`	The service account this send authenticates as.
`remapData`	Whether Courier remaps `data` for this send.

Put personalization variables in message.data, not in to. Courier reads anything nested in to as profile data, so it fills no template variables and triggers no data mapping.

Custom data not reaching the device? covers the one template setting that stops it.

Override the payload

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
      ],
    },
    providers: {
      "firebase-fcm": {
        override: {
          body: {
            data: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE",
            },
            apns: {
              payload: {
                aps: {
                  sound: "ping.aiff",
                  badge: 99,
                },
              },
            },
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "firebase-fcm": {
                "override": {
                    "body": {
                        "data": {
                            "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
                        },
                        "apns": {
                            "payload": {
                                "aps": {
                                    "sound": "ping.aiff",
                                    "badge": 99,
                                },
                            },
                        },
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "firebase-fcm": {
          "override": {
            "body": {
              "data": {
                "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
              },
              "apns": {
                "payload": {
                  "aps": {
                    "sound": "ping.aiff",
                    "badge": 99
                  }
                }
              }
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push"
      ]
    },
    providers: {
      "firebase-fcm": {
        override: {
          body: {
            data: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE"
            },
            apns: {
              payload: {
                aps: {
                  sound: "ping.aiff",
                  badge: 99
                }
              }
            }
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "single",
		},
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"data": map[string]any{
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
						},
						"apns": map[string]any{
							"payload": map[string]any{
								"aps": map[string]any{
									"sound": "ping.aiff",
									"badge": 99,
								},
							},
						},
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "data", java.util.Map.of(
                            "YOUR_CUSTOM_KEY", "YOUR_CUSTOM_VALUE"
                        ),
                        "apns", java.util.Map.of(
                            "payload", java.util.Map.of(
                                "aps", java.util.Map.of(
                                    "sound", "ping.aiff",
                                    "badge", 99
                                )
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'body' => [
            'data' => [
              'YOUR_CUSTOM_KEY' => 'YOUR_CUSTOM_VALUE',
            ],
            'apns' => [
              'payload' => [
                'aps' => [
                  'sound' => 'ping.aiff',
                  'badge' => 99,
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.Single },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "data": {
                              "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
                            },
                            "apns": {
                              "payload": {
                                "aps": {
                                  "sound": "ping.aiff",
                                  "badge": 99
                                }
                              }
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.providers '{"firebase-fcm": {"override": {"body": {"data": {"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"}, "apns": {"payload": {"aps": {"sound": "ping.aiff", "badge": 99}}}}}}}'

With Courier MCP, send my template to user_123 on push, with an FCM sound and badge.

Provider details

firebase-fcm

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send push with Firebase Cloud Messaging through Courier

Prerequisites

Setup

Configure FCM provider

Enable iOS support (if required)

Profile requirements

Set up push notifications

Send by user id

Send to a recipient

Overrides

Override the payload

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Configure FCM provider

​Enable iOS support (if required)

​Profile requirements

Set up push notifications

Send by user id

​Send to a recipient

​Overrides

​Override the payload

​Provider details

Send to a specific provider

Prerequisites

Setup

Configure FCM provider

Enable iOS support (if required)

Profile requirements

Send to a recipient

Overrides

Override the payload

Provider details