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 must be a registration token, notification key, or topic. Do not set this field when sending to multiple topics. See condition.
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 an FCM connection server can simultaneously store 4 different send-to-sync messages per client app. If you exceed this number, there is no guarantee which 4 collapse keys the FCM connection server 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 wake a sleeping device and open a network connection to your server.

For more information, see Setting the priority of a message.
content_available Optional, JSON 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 awakened. On Android, data messages wake the app by default. On Chrome, this parameter is currently not supported.
delay_while_idle
Deprecated Effective Nov 15th 2016		 Optional, JSON boolean

This parameter is deprecated. After Nov 15th 2016, it will be accepted by FCM, but ignored.

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

The default value is false.
time_to_live Optional, JSON 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.

delivery_receipt_
requested		 Optional, JSON boolean

This parameter lets the app server request confirmation of message delivery.

When this parameter is set to true, CCS 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, JSON 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, JSON 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 sent via APNs, it represents the custom data fields. If it is sent via the FCM connection server, 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, JSON object This parameter specifies the 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.

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 Indicates notification title. This field is not visible on iOS phones and tablets.
body Optional, string Indicates notification body text.
sound Optional, string

Indicates a sound to play when the device receives a 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 Indicates the badge on the client app home icon.
click_action Optional, string

Indicates the action associated with a user click on the notification. Corresponds to category in the APNs payload.
body_loc_key Optional, string

Indicates the key to the body string for localization. Corresponds to "loc-key" in the APNs payload.
body_loc_args Optional, JSON array as string

Indicates the string value to replace format specifiers in the body string for localization. Corresponds to "loc-args" in the APNs payload.
title_loc_key Optional, string

Indicates the key to the title string for localization. Corresponds to "title-loc-key" in the APNs payload.
title_loc_args Optional, JSON array as string

Indicates the string value to replace format specifiers in the title string for localization.Corresponds to "title-loc-args" in the APNs payload.

Table 2b. Android — keys for notification messages

Parameter Usage Description
title Optional, string Indicates notification title.
body Optional, string Indicates notification body text.
icon Optional, string Indicates notification icon. Sets value 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

Indicates a sound to play when the device receives a notification. Supports default or the filename of a sound resource bundled in the app. Sound files must reside in /res/raw/.
tag Optional, string Indicates whether each notification results in a new entry in the notification drawer on Android.
If not set, each request creates a new notification.
If set, 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 Indicates color of the icon, expressed in #rrggbb format
click_action Optional, string

Indicates the action associated with a user click on the notification. When this is set, an activity with a matching intent filter is launched when user clicks the notification.
body_loc_key Optional, string

Indicates the key to the body string for localization. Use the key in the app's string resources when populating this value.
body_loc_args Optional, JSON array as string

Indicates the string value to replace format specifiers in the body string for localization. For more information, see Formatting and Styling.
title_loc_key Optional, string

Indicates the key to the title string for localization. Use the key in the app's string resources when populating this value.
title_loc_args Optional, JSON array as string

Indicates the string value to replace format specifiers in the title string for localization. For more information, see Formatting strings.

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

Parameter Usage Description
title Optional, string Indicates notification title.
body Optional, string Indicates notification body text.
icon Optional, string The URL for a notification icon.
click_action Optional, string

Indicates the action associated with a user click on the notification. For all URL values, secure 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 the XMPP connection server 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.

registration_id Optional, string This parameter specifies the canonical registration token for the client app that the message was processed and sent to. A canonical registration ID is the registration token of the last registration requested by the client app. This is the ID that the server should use when sending messages to the device.
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 BAD_REGISTRATION 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 or notification messages on iOS. 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, the XMPP connection server needs to close down a connection to perform load balancing. Retry the message over another XMPP connection.

Upstream message syntax

An upstream message is a message the client app sends to the app server. Currently only CCS (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 CCS 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 the XMPP connection server 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.

Cloud Connection Server Messages (XMPP)

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

  • Delivery Receipt: If the app server included delivery_receipt_requested in the downstream message, the XMPP connection server 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 Cloud Connection Server messages (XMPP).

Parameter Usage Description
Common field
message_type Required, string

This parameter specifies the type of the CCS 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 CCS.
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 CCS.

Currently, only CONNECTION_DRAINING is supported. The XMPP connection server 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.

Send feedback about...

This page
Documentation feedback
Firebase
Firebase
Product feedback
Need help? Visit our support page.