Firebase Cloud Messaging (FCM) offers a broad range of messaging options
and capabilities. The information in this page is intended to
help you understand the different types of FCM messages and what you
can do with them.
Message types
With FCM, you can send two types of messages to clients:
- Notification messages, sometimes thought of as "display messages." These 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.
Data messages, by contrast, contain only your user-defined custom key-value
pairs. Notification messages can contain an optional
data payload. Maximum payload for both message types is 4096 bytes, except when
sending messages from the Firebase console, which enforces a 1000 character
limit.
|
Use scenario
|
How to send
|
Notification message
|
FCM SDK displays the message to end-user devices
on behalf of the client app when it's running in the background.
Otherwise, if the app is running in the foreground when the
notification is received, the app's code determines the behavior.
Notification messages have a predefined set of user-visible keys and an
optional data payload of custom key-value pairs.
|
In a trusted environment such as
Cloud Functions
or your app server, use the
Admin SDK or the
HTTP v1 API
. Set the
notification
key.
May have optional data payload. Always collapsible.
See some
examples of display notifications
and send request payloads.
- Use the
Notifications composer
: Enter the Message Text, Title, etc., and send.
Add optional data payload by providing Custom data.
|
Data message
|
Client app is responsible for processing data messages. Data messages
have only custom key-value pairs with no reserved key names (see below).
|
In a trusted environment such as
Cloud Functions
or your app server, use the
Admin SDK or the
FCM Server Protocols
. In the send request, Set the
data
key.
|
Use notification messages when you want the FCM SDK to handle displaying
a notification automatically when your app is running in the background.
Use data messages when you want to process the messages with your
own client app code.
FCM can send a notification message including an optional data
payload. In such cases, FCM handles displaying the notification
payload, and the client app handles the data payload.
Notification messages
For testing or for marketing and user re-engagement, you can
send
notification messages using the Firebase console
.
The Firebase console provides analytics-based
A/B testing
to help you refine and
improve marketing messages.
To programmatically send notification messages using the Admin SDK or the
FCM protocols, set the
notification
key with the
necessary predefined set of key-value options for the user-visible
part of the notification message. For example, here is a JSON-formatted
notification message in an IM app. The user can expect to see a
message with the title "Portugal vs. Denmark" and the text
"great match!" on the device:
{
"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.
See the
HTTP v1 Protocol notification object
reference documentation
for the full list of predefined keys available for building notification
messages.
Data messages
Set the appropriate key with your custom key-value pairs to
send a data payload to the client app.
For example, here is a
JSON-formatted message in the same IM app as above,
where the information is encapsulated in the common
data
key and
the client app is expected to interpret the content:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
}
}
}
The above 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.
Encryption for data messages
The Android Transport Layer
(see
FCM architecture
)
uses point-to-point encryption. Depending on your
needs, you may decide to add end-to-end encryption to data messages.
FCM does not provide an end-to-end solution.
However, there are external solutions available such
as
Capillary
or
DTLS
.
Notification messages with optional data payload
Both programmatically or via the Firebase console, you can send notification
messages that contain an optional payload of custom key-value pairs. 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"
}
}
}
The Firebase Admin SDK and the FCM v1 HTTP protocol both allow your message
requests to set all fields available in the
message
object. This includes:
- a common set of fields to be interpreted by
all
app instances that
receive the message.
- platform-specific sets of fields, such as
AndroidConfig
and
WebpushConfig
,
interpreted only by app instances running on the specified platform.
Platform-specific blocks give you flexibility to customize messages for
different platforms to ensure that they are handled correctly when received. The
FCM backend will take all specified parameters into account and customize the
message for each platform.
When to use common fields
Use common fields when you're:
- Targeting app instances on
all
platforms ? Apple, Android, and web
- Sending messages to topics
All app instances, regardless of platform, can interpret the following common
fields:
Use platform-specific fields when you want to:
- Send fields only to particular platforms
- Send platform-specific fields
in addition to
the common fields
Whenever you want to send values only to particular platforms,
don't
use
common fields; use platform-specific fields. For example, to send a notification
only to Apple platforms and web but not to Android, you must use two separate sets of
fields, one for Apple and one for web.
When you are sending messages with specific
delivery options
,
use platform-specific fields to set them.
You can specify different values per platform if
you want. However, even when you want to set essentially the same value across
platforms, you must use platform-specific fields. This is because each platform
may interpret the value slightly differently—for example, time-to-live is
set on Android as an expiration time in seconds, while on Apple it is set as an
expiration
date
.
The following v1 send request sends a common notification title and
content to all platforms, but also sends some platform-specific overrides.
Specifically, the request:
- sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
- sets the appropriate keys to define the result of a user tap on the notification on Android and Apple —
click_action
, and
category
, respectively.
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Match update",
"body":"Arsenal goal in added time, score is now 3-0"
},
"android":{
"ttl":"86400s",
"notification"{
"click_action":"OPEN_ACTIVITY_1"
}
},
"apns": {
"headers": {
"apns-priority": "5",
},
"payload": {
"aps": {
"category": "NEW_MESSAGE_CATEGORY"
}
}
},
"webpush":{
"headers":{
"TTL":"86400"
}
}
}
}
See the
HTTP v1 reference documentation
for complete detail on the keys available in
platform-specific blocks in the message body. For more information about
building send requests that contain the message body, see
Build Send Requests
.
Delivery options
FCM provides a specific set of delivery options for messages sent to
Android devices, and allows for similar options on
Apple platforms and web. For example, "collapsible" message behavior is supported on
Android via FCM's
collapse_key
, on Apple via
apns-collapse-id
, and on JavaScript/Web via
Topic
. For details, see
descriptions in this section and related reference documentation.
Non-collapsible and collapsible messages
A
non-collapsible
message denotes that each individual message is
delivered to the device. A non-collapsible message delivers some useful
content, as opposed to a collapsible message like a content-free "ping" to
the mobile app to contact the server to fetch data.
Some typical use cases of non-collapsible messages are chat messages or
critical messages.
For example, in an IM app, you would want to deliver every message, because
every message has different content.
For Android there is a limit of 100 messages that can be stored without
collapsing. If the
limit is reached, all stored messages are discarded. When the device is back
online, it receives a special message indicating that the limit was reached.
The app can then handle the situation properly, typically by requesting a full
sync from the app server.
A
collapsible message
is a message that may be replaced by a
new message if it has yet to be delivered to the device.
A common use cases of collapsible messages are messages used to tell
a mobile app to sync data from the server. An
example would be a sports app that updates users with the latest score.
Only the most recent message is relevant.
To mark a message as collapsible on Android, include the
collapse_key
parameter in
the message payload. By default, the collapse key is the app package name
registered in the Firebase console. The FCM server can
simultaneously store four different collapsible messages per
device, each with a different collapse key. If you exceed this number,
FCM only keeps
four collapse keys, with no guarantees about which ones are kept.
Topic messages with no payload are collapsible by default. Notification messages
are always collapsible and will ignore the
collapse_key
parameter.
Which should I use?
Collapsible messages are a better choice from a performance standpoint,
provided your app doesn't need to use non-collapsible messages. However,
if you use collapsible messages, remember that
FCM only allows a maximum of four different collapse keys to be used
by FCM per
registration token at any given time. You must not exceed this number, or it
could cause unpredictable consequences.
|
Use scenario
|
How to send
|
Non-collapsible
|
Every message is important to the client app and needs to be
delivered.
|
Except for notification messages, all messages are non-collapsible by
default.
|
Collapsible
|
When there is a newer message that renders an older, related message
irrelevant to the client app, FCM replaces the older message.
For example:
messages used to initiate a data sync from the server, or outdated
notification messages.
|
Set the appropriate parameter in your message request:
collapseKey
on Android
apns-collapse-id
on Apple
Topic
on Web
collapse_key
in legacy protocols
(all platforms)
|
Setting the priority of a message
You have two options for assigning delivery priority to downstream messages:
normal and high priority. Though the behavior differs slightly across
platforms, delivery of normal and high priority messages works
like this:
Normal priority.
Normal priority messages are delivered immediately when the app is in the
foreground. For backgrounded apps, delivery may be
delayed. For less time-sensitive messages, such as
notifications of new email, keeping your UI in sync, or syncing app data in
the background, choose normal delivery priority.
High priority.
FCM attempts to deliver high priority
messages immediately even if the device is in Doze mode.
High priority messages are for time-sensitive, user visible content.
Here is an example of a normal priority message sent via the FCM
HTTP v1 protocol to notify a magazine
subscriber that new content is available to download:
{
"message":{
"topic":"subscriber-updates",
"notification":{
"body" : "This week's edition is now available.",
"title" : "NewsMagazine.com",
},
"data" : {
"volume" : "3.21.15",
"contents" : "http://www.news-magazine.com/world-week/21659772"
},
"android":{
"priority":"normal"
},
"apns":{
"headers":{
"apns-priority":"5"
}
},
"webpush": {
"headers": {
"Urgency": "high"
}
}
}
}
For more platform-specific detail on setting message priority:
Setting the lifespan of a message
FCM usually delivers messages immediately after they are sent.
However, this might not always be possible. For example, if the platform is
Android, the device could be turned off, offline, or otherwise unavailable.
Or FCM might intentionally delay messages
to prevent an app from consuming excessive resources and negatively
affecting battery life.
When this happens, FCM stores the message and delivers it as soon
as it's feasible. While this is fine in most cases, there are some apps for
which a late message might as well never be delivered. For example, if the
message is an incoming call or video chat notification, it is meaningful only
for a short period of time before the call is terminated. Or if the message is
an invitation to an event, it is useless if received after the event has ended.
On Android and Web/JavaScript, you can specify the maximum lifespan of a
message. The value must be a duration from 0 to 2,419,200 seconds (28
days), and it corresponds to the maximum period of time for which FCM
stores and attempts to deliver the message. Requests that don't contain this
field default to the maximum period of four weeks.
Here are some possible uses for this feature:
- Video chat incoming calls
- Expiring invitation events
- Calendar events
Another advantage of specifying the lifespan of a message is that
FCM doesn't apply collapsible message throttling to messages with a
time-to-live value of 0 seconds.
FCM provides best effort handling of messages that must be
delivered "now or never." Keep in mind that a
time_to_live
value of
0 means messages that can't be delivered immediately are discarded. However,
because such messages are never stored, this provides the best latency for
sending notification messages.
Here is an example of a request that includes TTL:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
},
"apns":{
"headers":{
"apns-expiration":"1604750400"
}
},
"android":{
"ttl":"4500s"
},
"webpush":{
"headers":{
"TTL":"4500"
}
}
}
}
Lifetime of a message
When an app server posts a message to FCM and receives a message
ID back, it does not mean that the message was already delivered to the
device. Rather, it means that it was accepted for delivery. What happens to
the message after it is accepted depends on many factors.
In the best-case scenario, if the device is connected to FCM,
the screen is on and there are no throttling restrictions, the message is
delivered right away.
If the device is connected but in Doze, a low priority message is stored
by FCM until the device is out of Doze. And
that's where the
collapse_key
flag plays a role: if there is
already a message with the same collapse key (and registration token) stored
and waiting for
delivery, the old message is discarded and the new message takes its place
(that is, the old message is collapsed by the new one). However, if the collapse
key is not set, both the new and old messages are stored for future delivery.
If the device is not connected to FCM, the message is stored until
a connection is established (again respecting the collapse key rules). When a
connection is established, FCM delivers all pending messages to the
device. If the device never gets connected again
(for instance, if it was factory reset), the message eventually times out and
is discarded from FCM storage. The default timeout is four weeks,
unless the
time_to_live
flag is set.
To get more insight into the delivery of a message:
To get more insight into the delivery of messages on Android or Apple platforms, see
the
FCM reporting dashboard
, which records the
number of messages sent and opened on Apple and Android devices, along with
data for "impressions" (notifications seen by users) for Android apps.
For Android devices with direct channel messaging enabled, if the
device has not connected to FCM for more than one month,
FCM still accepts the message but immediately discards it. If the
device connects within four weeks of the last data message you sent to it,
your client receives the
onDeletedMessages()
callback.
The app can then handle the situation properly, typically by requesting a full
sync from the app server.
Finally, when FCM attempts to deliver a message to the device and
the app was uninstalled, FCM discards that message right away and
invalidates the registration token. Future attempts to send a message to that
device results in a
NotRegistered
error.
Throttling and scaling
Our goal is to always deliver every message sent via FCM. However,
delivering every message sometimes results in a poor overall user experience.
In other cases, we need to provide boundaries to ensure that FCM provides a
scalable service for all senders.
Collapsible message throttling
As described above, collapsible messages are content-free notifications designed
to collapse on top of each other. In the event that a developer is repeating the
same message to an app too frequently, we delay (throttle) messages to reduce
the impact on a user’s battery.
For example, if you send large numbers of new email sync requests to a single
device, we might delay the next email sync request a few minutes so that the
device can sync at a lower average rate. This throttling is done strictly to
limit the battery impact experienced by the user.
If your use case requires high burst send patterns, then non-collapsible messages may
be the right choice. For such messages, make sure to include the content in
such messages in order to reduce the battery cost.
We limit collapsible messages to a burst of 20 messages per app per device, with
a refill of 1 message every 3 minutes.
XMPP server throttling
We limit the rate that you can connect to FCM XMPP servers to 400 connections
per minute per project. This shouldn't be an issue for message delivery, but it
is important for ensuring the stability of the system. For each project,
FCM allows 2500 connections in parallel.
For upstream messaging with XMPP, FCM limits
upstream messages
at 1,500,000/minute
per project to avoid overloading upstream destination servers.
We limit upstream messages per device at 1,000/minute to protect against battery
drain from bad app behavior.
Maximum message rate to a single device
For Android, you can send up to 240 messages/minute and 5,000 messages/hour to a single
device. This high threshold is meant to allow for short term bursts of traffic,
such as when users are interacting rapidly over chat. This limit prevents errors
in sending logic from inadvertently draining the battery on a device.
For iOS, we return an error when the rate exceeds APNs limits.
Topic message limit
The topic subscription add/remove rate is limited to 3,000 QPS per project.
For message sending rates, see
Fanout Throttling
.
Fanout throttling
Message fanout is the process of sending a message to multiple devices, such as
when you target topics and groups, or when you use the
Notifications composer
to target audiences or user segments.
Message fanout is not instantaneous and so occasionally you have multiple
fanouts in progress concurrently. We limit the number of concurrent message
fanouts per project to 1,000. After that, we may reject additional fanout
requests or defer the fanout of the requests until some of the already in
progress fanouts complete.
The actual achievable fanout rate is influenced by the number of projects
requesting fanouts at the same time. A fanout rate of 10,000 QPS for an
individual project is not uncommon, but that number is not a guarantee and is a
result of the total load on the system. It is important to note that the
available fanout capacity is divided among projects and not across fanout
requests. So, if your project has two fanouts in progress, then each fanout will
only see half of the available fanout rate. The recommended way to maximize your
fanout speed is to only have one active fanout in progress at a time.
FCM ports and your firewall
If your organization has a firewall to restrict traffic to or
from the Internet, you need to configure it to allow mobile devices to connect
with FCM in order for devices on your network to receive messages.
FCM typically uses port 5228, but it sometimes uses 443, 5229, and
5230.
For devices connecting on your network, FCM doesn't provide
specific IPs because our IP range changes too frequently and your firewall rules
could get out of date, impacting your users' experience. Ideally, allowlist
ports 5228-5230 & 443 with no IP restrictions. However, if you must have an IP
restriction, you should allowlist all of the IP addresses listed in
goog.json
.
This large list is updated regularly, and you are recommended to update your
rules on a monthly basis. Problems caused by
firewall IP restrictions are often intermittent and difficult to diagnose.
We do offer a set of domain names that can be allowlisted instead of IP
addresses. Those hostnames are listed below. If we start using additional
hostnames, we will update the list here. Using domain names for your firewall
rule may or may not be functional in your firewall device.
TCP ports to open:
Hostnames to open:
- mtalk.google.com
- mtalk4.google.com
- mtalk-staging.google.com
- mtalk-dev.google.com
- alt1-mtalk.google.com
- alt2-mtalk.google.com
- alt3-mtalk.google.com
- alt4-mtalk.google.com
- alt5-mtalk.google.com
- alt6-mtalk.google.com
- alt7-mtalk.google.com
- alt8-mtalk.google.com
- android.apis.google.com
- device-provisioning.googleapis.com
- firebaseinstallations.googleapis.com
Network Address Translation and/or Stateful Packet Inspection firewalls:
If your network implements Network Address Translation (NAT) or Stateful Packet
Inspection (SPI), implement a 30 minute or larger timeout
for our connections over ports 5228-5230. This enables us to provide reliable
connectivity while reducing the battery consumption of your users' mobile
devices.
VPN interactions and bypassability
Firebase Cloud Messaging takes various steps to ensure that the push messaging
connection from the phone to the server is reliable and available as often as
possible. The use of a VPN complicates this effort.
VPNs mask the underlying information that FCM needs to tune its
connection to maximize reliability & battery life. In some cases VPNs actively
break long lived connections resulting in a bad user experience due to missed or
delayed messages or a high battery cost. When the VPN is configured to allow us
to do so, we bypass the VPN using an encrypted connection (over the base network
wifi or LTE) so as to ensure a reliable, battery friendly
experience. FCM's usage of bypassable VPNs is specific to the
FCM Push Notification channel. Other FCM traffic, such as
registration traffic, uses the VPN if it is active. When the FCM
connection bypasses the VPN it loses additional benefits the VPN may provide,
such as IP masking.
Different VPNs will have different methods for controlling whether or not it can
be bypassed. Consult the documentation for your specific VPN for instructions.
If the VPN is not configured to be bypassable then Firebase Cloud Messaging will
use the VPN network in order to connect to the server. This may result in
periods of time where messages are delayed and may result in more battery
usage as Cloud Messaging works to maintain the connection over the VPN
connection.
Credentials
Depending on which FCM features you implement, you may need the
following credentials from your Firebase project:
Project ID
|
A unique identifier for your Firebase project, used in requests to the
FCM v1 HTTP endpoint. This value is
available in the
Firebase console
Settings
pane.
|
Registration token
|
A unique token string that identifies each client app instance.
The registration token is required for single device and device
group messaging. Note that
registration tokens must be kept secret.
|
Sender ID
|
A unique numerical value created when you create your Firebase project,
available in the
Cloud Messaging
tab of the Firebase console
Settings
pane. The sender ID is used to identify each
sender that can send messages to the client app.
|
Access token
|
A short-lived OAuth 2.0 token that authorizes requests to the HTTP v1
API. This token is associated with a service account that belongs to
your Firebase project. To create and rotate access tokens, follow the
steps described in
Authorize Send Requests
.
|
Server key (for **deprecated** legacy protocols)
| A server
key that authorizes your app server for
access to Google services, including sending messages via the
deprecated Firebase Cloud Messaging
legacy protocols.
Important:
Do not include the server key anywhere in
your client code. Also, make sure to use only server keys to authorize your
app server. Android, Apple platform, and browser keys are rejected by
FCM.
|