Google is committed to advancing racial equity for Black communities. See how.

Send a test message to a backgrounded app

To get started with FCM, build out the simplest use case: sending a notification message to a specific user when the app is in the background on the device. This page lists all the steps to achieve this, from setup to verification — it may cover steps you already completed if you have set up a JavaScript client app for FCM.

Set up the SDK

If you haven't already, add Firebase to your JavaScript project.

Access the registration token

This section describes how to retrieve the registration token for an app instance, and how to monitor token refresh events. Because the token could be rotated after initial startup, you should monitor token refresh and always retrieve the latest updated registration token.

The registration token may change when:

  • The web app deletes the registration token.
  • The user clears browser data. In this case, call getToken to retrieve the new token.

Retrieve the current registration token

When you need to retrieve the current token, call getToken. If notification permission has not been granted, this method will ask the user for notification permissions. Otherwise, it returns a token or rejects the promise due to an error.

The messaging service requires a firebase-messaging-sw.js file. Unless you already have a firebase-messaging-sw.js file, create an empty file with that name and place it in the root of your domain before retrieving a token. You can add meaningful content to the file later in the client setup process.

To retrieve the current token:

// Get Instance ID token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken().then((currentToken) => {
  if (currentToken) {
  } else {
    // Show permission request.
    console.log('No Instance ID token available. Request permission to generate one.');
    // Show permission UI.
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  showToken('Error retrieving Instance ID token. ', err);

Monitor token refresh

The onTokenRefreshcallback fires whenever a new token is generated, so calling getToken in its context ensures that you are accessing a current, available registration token.

// Callback fired if Instance ID token is updated.
messaging.onTokenRefresh(() => {
  messaging.getToken().then((refreshedToken) => {
    console.log('Token refreshed.');
    // Indicate that the new Instance ID token has not yet been sent to the
    // app server.
    // Send Instance ID token to app server.
    // ...
  }).catch((err) => {
    console.log('Unable to retrieve refreshed token ', err);
    showToken('Unable to retrieve refreshed token ', err);

After you've obtained the token, send it to your app server and store it using your preferred method.

Send a test notification message

  1. Install and run the app on the target device.

  2. Make sure the app is in the background on the device.

  3. Open the Notifications composer and select New notification.

  4. Enter the message text.

  5. Select Send test message.

  6. In the field labeled Add an FCM registration token, enter the registration token you obtained in a previous section of this guide.

  7. Click Test

After you click Test, the targeted client device (with the app in the background) should receive the notification in the browser.

Next steps

Send messages to foregrounded apps

Once you have successfully sent notification messages while your app is in the background, see Receive Messages in a JavaScript Client to get started sending to foregrounded apps.

Go beyond notification messages

To go beyond notification messages and add other, more advanced behavior to your app, see: