Firebase Cloud Messaging message types

With FCM, you can send two types of messages to your client apps:

• Notification messages, similar to "display messages", are handled by the FCM SDK automatically.
• Data messages, which are handled by the client app.

Notification messages contain a predefined set of user-visible keys and can contain an optional data payload. Data messages, by contrast, contain only your user-defined custom key-value pairs. Maximum payload for both message types is 4096 bytes, except when sending messages from the Firebase console, which enforces a 1000 character limit.

You can use notification messages when you want the FCM SDK to handle displaying a notification automatically when your app is running in the background. FCM can send a notification message with an optional data payload. In such cases, FCM displays the notification payload, and the client app handles the data payload.

You can use data messages when you want to process the messages with your own client app code.

Notification messages

You can send notification messages using the Firebase console, the Firebase Admin SDK, or the FCM HTTP v1 API. The Firebase console provides analytics-based A/B testing to help you refine and improve your notification messages.

To send notification messages using the Firebase Admin SDK or the FCM HTTP v1 API, set the notification key with the predefined set of key-value options of the notification message. You can use the following example to format a notification message in an IM app

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

Notification messages are delivered to the notification tray when the app is in the background. For apps in the foreground, messages are handled by a callback function.

You can use the FCM HTTP v1 API notification object reference documentation for the full list of predefined keys available for building notification messages.

Data messages

It is up to you how you want to use the FCM payload data to implement your encryption scheme of choice. Make sure that you don't use any reserved words in your custom key-value pairs. Reserved words include from, message_type, or any word starting with google., gcm. or gcm.notification..

The following example shows usage of the top-level, or common data field, which is interpreted by clients on all platforms that receive the message. On each platform, the client app receives the data payload in a callback function

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Notification messages with optional data payload

You can send notification messages that contain an optional payload of custom key-value pairs programmatically or using the Firebase console. In the Notifications composer, use the Custom data fields in Advanced options.

App behavior when receiving messages that include both notification and data payloads depends on whether the app is in the background or the foreground—essentially, whether or not it is active at the time of receipt.

• When in the background, apps receive the notification payload in the notification tray, and only handle the data payload when the user taps on the notification.
• When in the foreground, your app receives a message object with both payloads available.

Here is a JSON-formatted message containing both the notification key and the data key:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}