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.

HTTP Connection Server Reference

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

Downstream message syntax

This section gives the syntax for sending downstream messages and interpreting HTTP responses from GCM.

Downstream HTTP messages (JSON)

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

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

Parameter Usage Description
Targets
to Required, string

This parameter specifies the recipient of a message.

The value must be a registration token, notification key, or topic.

registration_ids
String array

This parameter specifies a list of devices (registration tokens, or IDs) receiving a multicast message. It must contain at least 1 and at most 1000 registration tokens.

Use this parameter only for multicast messaging, not for single recipients. Multicast messages (sending to more than 1 registration tokens) are allowed using HTTP JSON format only.

notification_key
Deprecated
Optional, string

This parameter is deprecated. Instead, use to to specify message recipients. For more information on how to send messages to multiple devices using to, see Device Group Messaging.

Options
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 becomes active.

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.

restricted_package_
name
Optional, string This parameter specifies the package name of the application where the registration tokens must match in order to receive the message.
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 custom 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 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 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.

Downstream HTTP messages (Plain Text)

The following table lists the syntax for targets, options, and payload in plain text downstream HTTP messages.

Table 3. Targets, options, and payload for downstream plain text HTTP messages.

Parameter Usage Description
Targets
registration_id Required, string

This parameter specifies the client apps (registration IDs) receiving the message.

Multicast messaging (sending to more than one registration ID) is allowed using HTTP JSON format only.

Options
collapse_key Optional, string See table 1 for details.
time_to_live Optional, number See table 1 for details.
restricted_package_name Optional, string See table 1 for details.
dry_run Optional, boolean See table 1 for details.
Payload
data.<key> Optional, string

This parameter specifies the key-value pairs of the message's payload. There is no limit on the number of key-value parameters, but there is a total message size limit of 4kb.

For instance, in Android, "data.score"."3x1" would result 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).

Interpreting a downstream message response

The app server should evaluate both the message response header and the body to interpret the message response sent from GCM. The following table describes the possible responses.

Table 4. Downstream HTTP message response header.

Response Description
200 Message was processed successfully. The response body will contain more details about the message status, but its format will depend whether the request was JSON or plain text. See table 5 for more details.
400 Only applies for JSON requests. Indicates that the request could not be parsed as JSON, or it contained invalid fields (for instance, passing a string where a number was expected). The exact failure reason is described in the response and the problem should be addressed before the request can be retried.
401 There was an error authenticating the sender account.
5xx Errors in the 500-599 range (such as 500 or 503) indicate that there was an internal error in the GCM connection server while trying to process the request, or that the server is temporarily unavailable (for example, because of timeouts). Sender must retry later, honoring any Retry-After header included in the response. Application servers must implement exponential back-off.

The following table lists the fields in a downstream message response body (JSON).

Table 5. Downstream HTTP message response body (JSON).

Parameter Usage Description
multicast_id Required, number Unique ID (number) identifying the multicast message.
success Required, number Number of messages that were processed without an error.
failure Required, number Number of messages that could not be processed.
canonical_ids Required, number Number of results that contain a canonical registration token. See the registration overview for more discussion of this topic.
results Optional, array object Array of objects representing the status of the messages processed. The objects are listed in the same order as the request (i.e., for each registration ID in the request, its result is listed in the same index in the response).
  • message_id: String specifying a unique ID for each successfully processed message.
  • registration_id: Optional string specifying the canonical registration token for the client app that the message was processed and sent to. Sender should use this value as the registration token for future requests. Otherwise, the messages might be rejected.
  • error: String specifying the error that occurred when processing the message for the recipient. The possible values can be found in table 9.

Table 6. Topic message HTTP response body (JSON).

Parameter Usage Description
message_id Optional, number The topic message ID when GCM has successfully received the request and will attempt to deliver to all subscribed devices.
error Optional, string Error that occurred when processing the message. The possible values can be found in table 9.

Table 7. Success response for downstream HTTP message response body (Plain Text).

Parameter Usage Description
id Required, string This parameter specifies the unique message ID that GCM connection server processed successfully.
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.

Table 8. Error response for downstream HTTP message response body (Plain Text).

Parameter Usage Description
Error Required, string This parameter specifies the error value while processing the message for the recipient. See table 9 for details.

Downstream message error response codes

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

Table 9. Downstream message error response codes.

Error HTTP Code Recommended Action
Missing Registration Token 200 + error:MissingRegistration 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 200 + error:InvalidRegistration 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 200 + error:NotRegistered 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.
Invalid Package Name 200 + error:InvalidPackageName Make sure the message was addressed to a registration token whose package name matches the value passed in the request.
Authentication Error 401 The sender account used to send a message couldn't be authenticated. Possible causes are:
  • Authorization header missing or with invalid syntax in HTTP request.
  • Invalid project number sent as key.
  • Key valid but with GCM service disabled.
  • Request originated from a server not whitelisted in the Server Key IPs.
Check that the token you're sending inside the Authentication header is the correct server key associated with your project. See Checking the validity of a server key for details.
Mismatched Sender 200 + error:MismatchSenderId 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 400 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 200 + error:MessageTooBig 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 200 + error:
InvalidDataKey
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 200 + error:InvalidTtl 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).
Timeout 5xx or 200 + error:Unavailable

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

  • Honor the Retry-After header if it is included in the response from the GCM Connection Server.
  • 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.

Senders that cause problems risk being blacklisted.

Internal Server Error 500 or 200 + error:InternalServerError 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 200 + error:
DeviceMessageRate
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 200 + error:
TopicsMessageRate
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.
Invalid APNs credentials 200 + error:
InvalidApnsCredential
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.

Send feedback about...

Cloud Messaging
Cloud Messaging