Firebase Cloud Messaging (FCM) is the new version of GCM. It inherits the reliable and scalable GCM infrastructure, plus new features! See the FAQ to learn more. If you are integrating messaging in a new app, start with FCM. GCM users are strongly recommended to upgrade to FCM, in order to benefit from new FCM features today and in the future. Before you go, please visit our GCM and FCM developer survey to give us feedback!

XMPP Connection Server Reference

This document provides a reference for the XMPP syntax used to pass messages between your app server, client apps, and GCM. The parameters and options fall into the following broad categories:

Downstream message syntax

This section gives the syntax for sending a downstream messages.

Downstream XMPP messages (JSON)

The following table lists the targets, options, and payload for XMPP JSON messages. For more information about downstream messaging, see Simple Downstream Messaging

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

Parameter Usage Description
Targets
to Required, string

This parameter specifies the recipient of a message.

The value must be a registration token or notification key.

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 can be resumed. This is intended to avoid sending too many of the same messages when the device comes back online or comes out of doze.

Note that 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 a GCM 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 GCM 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 priority 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 awoken. On Android, data messages wake the app by default. On Chrome, currently not supported.

mutable_content Optional, JSON boolean

Currently for iOS 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.

delay_while_idle
Deprecated Effective Nov 15th 2016
Optional, JSON boolean

This parameter is deprecated. After Nov 15th 2016, it will be accepted by GCM, 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 GCM 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 Android, this would result in an intent extra named score with the string value 3x1.

On iOS, if the message is sent via APNS, it represents the custom data fields. If it is sent via GCM connection server, it would be represented as key value dictionary in AppDelegate application:didReceiveRemoteNotification:.

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 Payload.

Notification payload support

The following table lists the predefined parameters available to use in notification messages.

Table 2. Parameters for notification messaging by platform

Parameter Platform Usage Description
title Android, iOS (Watch) Required (Android), Optional (iOS), string Indicates notification title. This field is not visible on iOS phones and tablets.
body Android, iOS Optional, string Indicates notification body text.
icon Android Required, string Indicates notification icon. On Android: sets value to myicon for drawable resource myicon.
sound Android, iOS Optional, string

Indicates a sound to play when the device receives the notification. Supports default, or the filename of a sound resource bundled in the app.

Android sound files must reside in /res/raw/, while iOS 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 iOS Optional, string Indicates the badge on client app home icon.
tag Android Optional, string Indicates whether each notification message results in a new entry on the notification center 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 notification center.
color Android Optional, string Indicates color of the icon, expressed in #rrggbb format
click_action Android, iOS Optional, string

The action associated with a user click on the notification.

On Android, if this is set, an activity with a matching intent filter is launched when user clicks the notification.

If set on iOS, corresponds to category in APNS payload.

body_loc_key Android, iOS Optional, string

Indicates the key to the body string for localization.

On iOS, this corresponds to "loc-key" in APNS payload.

On Android, use the key in the app's string resources when populating this value.

body_loc_args Android, iOS Optional, JSON array as string

Indicates the string value to replace format specifiers in body string for localization.

On iOS, this corresponds to "loc-args" in APNS payload.

On Android, these are the format arguments for the string resource. For more information, see Formatting strings.

title_loc_key Android, iOS Optional, string

Indicates the key to the title string for localization.

On iOS, this corresponds to "title-loc-key" in APNS payload.

On Android, use the key in the app's string resources when populating this value.

title_loc_args Android, iOS Optional, JSON array as string

Indicates the string value to replace format specifiers in title string for localization.

On iOS, this corresponds to "title-loc-args" in APNS payload.

On Android, these are the format arguments for the string resource. For more information, see Formatting strings.

Interpreting a downstream XMPP message response

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

Table 3. Downstream message XMPP message 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. Sender should replace the registration token with this value on future requests; otherwise, the messages might be rejected.
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 GCM. 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 GCM.
  • If the client app is automatically unregistered, which can happen if the user uninstalls the application. For example, on iOS, if the APNS Feedback Service 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 GCM, 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 GCM 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, or gcm, or any value prefixed by google) that is used internally by GCM. Note that some words (such as collapse_key) are also used by GCM but are allowed in the payload, in which case the payload value will be overridden by the GCM 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 back-off in your retry mechanism. (e.g. if you waited one second before the first retry, wait at least two second before the next one, then 4 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 1 second.

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). If the error persists, please report the problem in the android-gcm group.
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.
Invalid APNs Credentials INVALID_APNS_CREDENTIAL A message targeted to an iOS device could not be sent because the required APNs SSL certificate was not uploaded or has expired. Check the validity of your development and production certificates.

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 Send Upstream Messages for more information about sending messges 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 it (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. GCM 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 will continue to be processed.

Send feedback about...

Cloud Messaging
Cloud Messaging