Firebase Cloud Messaging XMPP protocol

This document provides a reference for the XMPP syntax used to pass messages between your app server, client apps, and Firebase Cloud Messaging (FCM). Your app server must connect to these endpoints:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

The available parameters and options fall into these categories:

Downstream message syntax

This section gives the syntax for sending downstream messages.

Downstream XMPP messages (JSON)

The following table lists the targets, options, and payload for XMPP JSON messages.

Table 1 Targets, options, and payload for downstream XMPP messages (JSON).

Parameter Usage Description
Target
to Optional, string

This parameter specifies the recipient of a message.

The value can be a device's registration token, a device group's notification key, or a single topic (prefixed with /topics/). To send to multiple topics, use the condition parameter.

condition Optional, string

This parameter specifies a logical expression of conditions that determines the message target.

Supported condition: Topic, formatted as "'yourTopic' in topics". This value is case-insensitive.

Supported operators: &&, ||. Maximum two operators per topic message supported.
Options
message_id Required, string

This parameter uniquely identifies a message in an XMPP connection.
collapse_key Optional, string

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 Apple platforms, 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 Apple platforms, 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 FCM. 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

On Apple platforms, 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.

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 Apple platforms, 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", "message_type", 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 Apple device, the message is sent through APNs, otherwise it is sent through FCM.

Notification payload support

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

Table 2a. Apple — keys for notification messages

Parameter Usage Description
title Optional, string

The notification's title.

This field is not visible on phones and tablets.

body Optional, string

The notification's body text.

sound Optional, string

The sound to play when the device receives the notification.

String specifying sound files 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.

Corresponds to loc-key in the APNs payload.

See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.

body_loc_args Optional, JSON array as string

Variable string values to be used in place of the format specifiers in body_loc_key to use to localize the body text to the user's current localization.

Corresponds to loc-args in the APNs payload.

See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.

title_loc_key Optional, string

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

Corresponds to title-loc-key in the APNs payload.

See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.

title_loc_args Optional, JSON array as string

Variable string values to be used in place of the format specifiers in title_loc_key to use to localize the title text to the user's current localization.

Corresponds to title-loc-args in the APNs payload.

See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.

Table 2b. Android — keys for notification messages

Parameter Usage Description
title Optional, string

The notification's title.

body Optional, string

The notification's body text.

android_channel_id Optional, string

The notification's channel id (new in Android O).

The app must create a channel with this channel ID before any notification with this channel ID is received.

If you don't send this channel ID in the request, or if the channel ID provided has not yet been created by the app, FCM uses the channel ID specified in the app manifest.

icon Optional, string

The notification's icon.

Sets the notification icon to myicon for drawable resource myicon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest.

sound Optional, string

The sound to play when the device receives the notification.

Supports "default" or the filename of a sound resource bundled in the app. Sound files must reside in /res/raw/.

tag Optional, string

Identifier used to replace existing notifications in the notification drawer.

If not specified, each request creates a new notification.

If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.

color Optional, string

The notification's icon color, expressed in #rrggbb format.

click_action Optional, string

The action associated with a user click on the notification.

If specified, an activity with a matching intent filter is launched when a user clicks on the notification.

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.

See String Resources for more information.

body_loc_args Optional, JSON array as string

Variable string values to be used in place of the format specifiers in body_loc_key to use to localize the body text to the user's current localization.

See Formatting and Styling for more information.

title_loc_key Optional, string

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

See String Resources for more information.

title_loc_args Optional, JSON array as string

Variable string values to be used in place of the format specifiers in title_loc_key to use to localize the title text to the user's current localization.

See Formatting and Styling for more information.

Table 2c. Web (JavaScript) — keys for notification messages

Parameter Usage Description
title Optional, string

The notification's title.

body Optional, string

The notification's body text.

icon Optional, string

The URL to use for the notification's icon.

click_action Optional, string

The action associated with a user click on the notification.

For all URL values, HTTPS is required.

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 APNs Registration INVALID_JSON For iOS registrations, check that the registration request from the client contains a valid APNs token and application ID.
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 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.
Authentication Failed AUTHENTICATION_FAILED Failed to authenticate with external push services. Check whether you are using the correct web push certificates.

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:

  • 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: control.

When it is set to control, the message includes control_type to indicate the type of control message.
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.