This parameter identifies a group of messages (e.g., with
collapse_key: "Updates Available") that can be collapsed so that only the
last message gets sent when delivery is resumed. This is intended to avoid sending too
many of the same messages when the device comes back online or comes out of doze.

There is no guarantee of the order in which messages get sent.

Note: A maximum of 4 different collapse keys is allowed at any given time. This means
FCM can simultaneously store 4 different
messages per client app. If you
exceed this number, there is no guarantee which 4 collapse keys FCM
will keep.

priority

Optional, string

Sets the priority of the message. Valid values are "normal" and "high." On iOS,
these correspond to APNs priorities 5 and 10.

By default, notification messages are sent with high priority, and data messages
are sent with normal priority. Normal priority optimizes the client app's
battery consumption and should be used unless immediate delivery is required.
For messages with normal priority, the app may receive the message with
unspecified delay.

When a message is sent with high priority, it is sent immediately, and the app
can display a notification.

content_available

Optional, boolean

On iOS, use this field to represent content-available in the APNs
payload. When a notification or message is sent and this is set to true, an
inactive client app is awoken, and the message is sent through APNs as a silent
notification and not through the FCM connection server. Note that silent notifications in
APNs are not guaranteed to be delivered, and can depend on factors such as the user
turning on Low Power Mode, force quitting the app, etc. On Android, data messages wake the
app by default. On Chrome, currently not supported.

mutable_content

Optional, JSON boolean

Currently for iOS 10+ devices only. On iOS, use this field to represent
mutable-content in the APNS payload. When a notification is sent and this is set
to true, the content of the notification can be modified before it is displayed,
using a
Notification Service app extension. This parameter will be ignored for Android and web.

time_to_live

Optional, number

This parameter specifies how long (in seconds) the message should be kept in FCM storage
if the device is offline. The maximum time to live supported is 4 weeks, and the default value is 4 weeks.
For more information, see Setting the lifespan of a message.

When this parameter is set to true, FCM sends a delivery receipt
when the device confirms that it received the message.

Note: this parameter is not supported for messages sent to iOS
devices. The default value is false.

dry_run

Optional, boolean

This parameter, when set to true, allows developers to test a
request without actually sending a message.

The default value is false.

Payload

data

Optional, object

This parameter specifies the key-value pairs of the message's payload.

For example, with data:{"score":"3x1"}:

On iOS, if the message is delivered by APNs, it represents the custom data fields. If
it is delivered by FCM,
it is represented as a key value dictionary in AppDelegate application:didReceiveRemoteNotification:.

On Android, this results in an intent extra named score with the string value 3x1.

The key should not be a reserved word ("from" or any word starting with
"google" or "gcm"). Do not use any of the words defined in this table
(such as collapse_key).

Values in string types are recommended. You have to convert values in objects or other non-string data types
(e.g., integers or booleans) to string.

notification

Optional, object

This parameter specifies the predefined, user-visible key-value pairs of the
notification payload. See Notification payload support for detail. For more information
about notification message and data message options, see
Message types. If a notification payload is provided, or the
content_available option is set to true for a message to an iOS
device, the message is sent through APNs, otherwise it is sent through
the FCM connection server.

Notification payload support

The following tables list the predefined
keys available for building notification messages for iOS and Android.

Table 2a. iOS — keys for notification messages

Parameter

Usage

Description

title

Optional, string

The notification's title.

This field is not visible on iOS phones and tablets.

body

Optional, string

The notification's body text.

sound

Optional, string

The sound to play when the device receives the notification.

Sound files can be in the main bundle of the client app or in the
Library/Sounds folder of the app's data container. See the
iOS Developer Library for more information.

badge

Optional, string

The value of the badge on the home screen app icon.

If not specified, the badge is not changed.

If set to 0, the badge is removed.

click_action

Optional, string

The action associated with a user click on the notification.

Corresponds to category in the APNs payload.

subtitle

Optional, string

The notification's subtitle.

body_loc_key

Optional, string

The key to the body string in the app's string resources to use to
localize the body text to the user's current localization.

Interpret a downstream XMPP message response

The following table lists the fields that appear in a downstream XMPP message response.

Table 3 Downstream message XMPP response body.

Parameter

Usage

Description

from

Required, string

This parameter specifies who sent this response.

The value is the registration token of the client app.

message_id

Required, string

This parameter uniquely identifies a message in an XMPP connection.
The value is a string that uniquely identifies the associated message.

message_type

Required, string

This parameter specifies an ack or nack message from
FCM to the app server.

If the value is set to nack, the app server should look at
error and error_description to get failure information.

error

Optional, string

This parameter specifies an error related to the downstream message. It is set when the
message_type is nack. See table 4 for details.

error_description

Optional, string

This parameter provides descriptive information for the error. It is set
when the message_type is nack.

Downstream message error response codes

The following table lists the error response codes for downstream messages.

Table 4 Downstream message error response codes.

Error

XMPP code

Recommended action

Missing Registration Token

INVALID_JSON

Check that the request contains a registration token (in the
registration_id in a plain text message, or in the to
or registration_ids field in JSON).

Invalid Registration Token

BAD_REGISTRATION

Check the format of the registration token you pass to the server. Make sure it
matches the registration token the client app receives from registering with FCM. Do not
truncate or add additional characters.

Unregistered Device

DEVICE_UNREGISTERED

An existing registration token may cease to be valid in a number of scenarios, including:

If the client app unregisters with FCM.

If the client app is automatically unregistered, which can happen if
the user uninstalls the application. For example, on iOS, if APNs
reported the APNs token as invalid.

If the registration token expires (for example, Google might decide to refresh
registration tokens, or the APNs token has expired for iOS devices).

If the client app is updated, but the new version is not configured to receive messages.

For all these cases, remove this registration token from the app
server and stop using it to send messages.

Mismatched Sender

SENDER_ID_MISMATCH

A registration token is tied to a certain group of senders. When a client app registers
for FCM, it must specify which senders are allowed to send messages. You should use one
of those sender IDs when sending messages to the client app. If you switch to a different
sender, the existing registration tokens won't work.

Invalid JSON

INVALID_JSON

Check that the JSON message is properly formatted and contains valid fields
(for instance, making sure the right data type is passed in).

Message Too Big

INVALID_JSON

Check that the total size of the payload data included in a message does
not exceed FCM limits: 4096 bytes for most messages or 2048 bytes in the case
of messages to topics. This includes both
the keys and the values.

Invalid Data Key

INVALID_JSON

Check that the payload data does not contain a key (such as from,
gcm, or any value
prefixed by google) that is used internally by FCM. Note that some words (such as collapse_key)
are also used by FCM but are allowed in the payload, in which case
the payload value is overridden by the FCM value.

Invalid Time to Live

INVALID_JSON

Check that the value used in time_to_live is an integer representing a
duration in seconds between 0 and 2,419,200 (4 weeks).

Bad ACK message

BAD_ACK

Check that the ack message is properly formatted before retrying. See
table 6 for details.

Timeout

SERVICE_UNAVAILABLE

The server couldn't process the request in time. Retry the same request, but you must:

Implement exponential backoff in your retry mechanism. (e.g. if you waited one second
before the first retry, wait at least two seconds before the next one, then four seconds, and so on).
If you're sending multiple messages, delay each one independently by an additional random amount
to avoid issuing a new request for all messages at the same time.

The initial retry delay should be set to one second.

Note: Senders that cause problems risk being blacklisted.

Internal Server Error

INTERNAL_SERVER_
ERROR

The server encountered an error while trying to process the request. You could retry
the same request following the requirements listed in "Timeout" (see row above).

Device Message Rate Exceeded

DEVICE_MESSAGE_RATE
_EXCEEDED

The rate of messages to a particular device is too high. Reduce the
number of messages sent to this device, and do not immediately retry sending to this device.

Topics Message Rate Exceeded

TOPICS_MESSAGE_RATE
_EXCEEDED

The rate of messages to subscribers to a particular topic is too high. Reduce the
number of messages sent for this topic, and do not immediately retry sending.

Connection Draining

CONNECTION_DRAINING

The message couldn't be processed because the connection is draining. This happens because,
periodically, FCM needs to close down a connection to perform load balancing. Retry the message over
another XMPP connection.

Invalid APNs Credentials

INVALID_APNS_CREDENTIAL

A message targeted to an iOS device could not be sent because the required APNs
authentication key was not uploaded or has expired. Check the validity of your development
and production credentials.

Upstream message syntax

An upstream message is a message the client app sends to the app server.
Currently only XMPP supports upstream messaging. See
the documentation for your platform for more
information about sending messages from client apps.

Interpreting an upstream XMPP message

The following table describes the fields in the XMPP stanza generated
by FCM in response to upstream message requests from client apps.

Table 5 Upstream XMPP messages.

Parameter

Usage

Description

from

Required, string

This parameter specifies who sent the message.

The value is the registration token of the client app.

category

Required, string

This parameter specifies the application package name of the client app that sent the message.

message_id

Required, string

This parameter specifies the unique ID of the message.

data

Optional, string

This parameter specifies the key-value pairs of the message's payload.

Sending an ACK message

The following table describes the ACK response that the app server is expected to send to
FCM in response to an
upstream message the app server received.

Table 6 Upstream XMPP message response.

Parameter

Usage

Description

to

Required, string

This parameter specifies the recipient of a response message.

The value must be a registration token of the client app that sent the upstream message.

message_id

Required, string

This parameter specifies which message the response is intended for. The value must be
the message_id value from the corresponding upstream message.

message_type

Required, string

This parameter specifies an ack message from an app server to CCS.
For upstream messages, it should always be set to ack.

FCM server messages (XMPP)

This is a message sent from FCM to an app server.
Here are the primary types of messages that FCM
sends to the app server:

Delivery Receipt: If the app server included delivery_receipt_requested
in the downstream message, FCM sends a delivery receipt when it receives confirmation
that the device received the message.

Control: These CCS-generated messages indicate that
action is required from the app server.

The following table describes the fields included in the messages CCS
sends to an app server.

Table 7 FCM control messages (XMPP).

Parameter

Usage

Description

Common field

message_type

Required, string

This parameter specifies the type of the message: either delivery receipt or control.

When it is set to receipt, the message includes from, message_id,
category, and data fields to provide additional information.

When it is set to control, the message includes control_type to indicate the
type of control message.

Delivery receipt-specific

from

Required, string

This parameter is set to gcm.googleapis.com, indicating that the
message is sent from FCM.

message_id

Required, string

This parameter specifies the original message ID that the receipt is intended for,
prefixed with dr2: to indicate that the message is a delivery receipt. An app
server must send an ack message with this message ID to acknowledge that it
received this delivery receipt. See table 6 for the ack message format.

category

Optional, string

This parameter specifies the application package name of the client app that
receives the message that this delivery receipt is reporting. This is available when
message_type is receipt.

data

Optional, string

This parameter specifies the key-value pairs for the delivery receipt message. This is available
when the message type is receipt.

message_status: This parameter specifies the status of the receipt message.
It is set to MESSAGE_SENT_TO_DEVICE to indicate the device has confirmed its receipt of
the original message.

original_message_id: This parameter specifies the ID of the original message
that the app server sent to the client app.

device_registration_id: This parameter specifies the registration token of the
client app to which the original message was sent.

Control-specific

control_type

Optional, string

This parameter specifies the type of control message sent from FCM.

Currently, only CONNECTION_DRAINING is supported. FCM sends this control message
before it closes a connection to perform load balancing. As the connection drains, no more messages
are allowed to be sent to the connection, but existing messages in the pipeline
continue to be processed.