Server Reference

This document provides a reference for the syntax used to pass messages back and forth in GCM. These messages fall into the following broad categories:

The following sections describe the basic requirements for sending messages.

Downstream Messages

This is the message that a 3rd-party app server sends to a client app.

A downstream message includes the following components:

  • Target: specifies the recipient of the message.
  • Options: specifies attributes of the message.
  • Payload: specifies additional content to be included in the message. Optional.

The syntax for each of these components is described in the tables below.

Sending a downstream message

This section gives the syntax for sending a downstream messages. For JSON, these messages can be either HTTP or XMPP. For plain text, these messages can only be HTTP.

Downstream HTTP or XMPP messages (JSON)

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

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

Parameter Protocol Usage Description
Targets
to XMPP Required, string

This parameter specifies the recipient of a message.

The value must be a registration ID or notification key.

This parameter is used in XMPP in place of registration_ids or notification_key in HTTP.
registration_ids HTTP Required if notification_key not present, string array

This parameter specifies the list of devices (registration IDs) receiving the message. It must contain at least 1 and at most 1000 registration IDs.

Multicast messages (sending to more than 1 registration IDs) are allowed using HTTP JSON format only.

This parameter or notification_key is used in HTTP in place of to in XMPP.
notification_key HTTP Required if registration_ids not present, string

This parameter specifies the mapping of a single user to multiple registration IDs associated with that user.

This allows a 3rd-party app server to send a single message to multiple app instances (typically on multiple devices) owned by a single user.

A 3rd-party app server can use notification_key as the target for a message instead of an individual registration ID (or array of registration IDs). The maximum number of members allowed for a notification_key is 20.

This parameter or registration_ids is used in HTTP in place of to in XMPP.

See User Notifications for details.
Options
message_id XMPP Required, string

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

This parameters 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 (see delay_while_idle).

Note that there is no guarantee of the order in which messages get sent.

Messages with collapse key are also called send-to-sync messages messages.

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.

delay_while_idle HTTP, XMPP Optional, JSON boolean 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 HTTP, XMPP 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.

The default value is 4 weeks.

delivery_receipt_
requested		 XMPP Optional, JSON boolean

This parameter lets 3rd-party 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.

The default value is false.
restricted_package_
name		 HTTP Optional, string This parameter specifies the package name of the application where the registration IDs must match in order to receive the message.
dry_run HTTP 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 HTTP, XMPP Optional, JSON object

This parameter specifies the key-value pairs of the message's payload. There is no limit on the number of key-value pairs, 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). It is also not recommended to use words defined in this table (such as collapse_key) because that could yield unpredictable outcomes.

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.

Downstream HTTP messages (Plain Text)

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

Table 2. 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 ID) 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.
delay_while_idle Optional, boolean or number 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). It is also not recommended to use words defined in this table (such as collapse_key) because that could yield unpredictable outcomes.

Interpreting a Downstream Message Response

This section describes the syntax of a response to a downstream message. A client app or the GCM Connection Server sends the response to 3rd-party app server upon processing the message request.

Interpreting a downstream HTTP message response

The 3rd-party app server should look at both the message response header and the body to interpret the message response sent from the GCM Connection Server. The following table describes the possible responses.

Table 3. 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 4 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. Troubleshoot
5xx Errors in the 500-599 range (such as 500 or 503) indicate that there was an internal error in the GCM 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. Troubleshoot

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

Table 4. 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 ID. See the 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 ID for the client app that the message was processed and sent to. Sender should use this value as the Registration ID 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 11 .

Table 5. 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 server processed successfully.
registration_id Optional, string This parameter specifies the canonical registration ID for the client app that the message was processed and sent to. Sender should replace the registration ID with this value on future requests, otherwise, the messages might be rejected.

Table 6. 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 11 for details.

Interpreting a downstream XMPP message response

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

Table 7. Downstream message XMPP message response body.

Parameter Usage Description
from Required, string

This parameter specifies who sent this response.

The value is the registration ID 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 XMPP (CCS) to the 3rd-party app server.

If the value is set to nack, the 3rd-party 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 6 for details.
error_description Optional, string This parameter provides descriptive information for the error. It is set when the message_type is nack.

Upstream Messages (XMPP)

An upstream message is a message the client app sends to the 3rd-party app server. Currently only CCS (XMPP) supports upstream messaging.

Interpreting an upstream XMPP message

The following table describes the fields that appear in an upstream XMPP message.

Table 8. Upstream XMPP messages.

Parameter Usage Description
from Required, string

This parameter specifies who sent the message.

The value is the registration ID 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 upstream XMPP message response

The following table describes the response that 3rd-party app server is expected to send to XMPP (CCS) in response to an upstream message it (the app server) received.

Table 9. 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 ID 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 a 3rd-party app server to CCS.

Cloud Connection Server Messages (XMPP)

This is a message sent from XMPP (CCS) to a 3rd-party app server. Here are the primary types of messages that XMPP (CCS) sends to the 3rd-party app server:

  • Delivery Receipt: If the 3rd-party app server included delivery_receipt_requested in the downstream message, XMPP (CCS) 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 3rd-party app server.

The following table describes the fields included in the messages CCS sends to a 3rd-party app server.

Table 10. 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. A 3rd-party app server must send an ack message with this message ID to acknowledge that it received this delivery receipt. See table 9 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 3rd-party app server sent to the client app.
  • device_registration_id: This parameter specifies the registration ID 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. XMPP (CCS) 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.

Downstream message error response codes (HTTP and XMPP)

The following table lists the error response codes for downstream messages (HTTP and XMPP).

Table 11. Downstream message error response codes.

Error HTTP Code XMPP Code Recommended Action
Missing Registration ID 200 + error:MissingRegistration INVALID_JSON Check that the request contains a registration ID (either in the registration_id in a plain text message, or in the registration_ids in JSON).
Invalid Registration ID 200 + error:InvalidRegistration BAD_REGISTRATION Check the format of the registration ID you pass to the server. Make sure it matches the registration ID the client app receives from registering with GCM. Do not truncate or add additional characters.
Unregistered Device 200 + error:NotRegistered DEVICE_UNREGISTERED An existing registration ID 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.
  • If the registration ID expires (for example, Google might decide to refresh registration IDs).
  • If the client app is updated but the new version is not configured to receive messages.
For all these cases, remove this registration ID from the 3rd-party app server and stop using it to send messages.
Invalid Package Name 200 + error:InvalidPackageName Make sure the message was addressed to a registration ID 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 API key associated with your project. See GCM HTTP Connection Server for details.
Mismatched Sender 200 + error:MismatchSenderId BAD_REGISTRATION A registration ID 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 IDs won't work.
Invalid JSON 400 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 200 + error:MessageTooBig INVALID_JSON Check that the total size of the payload data included in a message does not exceed 4096 bytes. This includes both the the keys and the values.
Invalid Data Key 200 + error:
InvalidDataKey		 INVALID_JSON Check that the payload data does not contain a key (such as from 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 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 N/A BAD_ACK Check that the 'ack' message is properly formatted before retrying. See table 9 for details.
Timeout 5xx or 200 + error:Unavailable SERVICE_UNAVAILABLE

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

  • For HTTP: 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.
  • For CCS: The initial retry delay should be set to 1 second.

Senders that cause problems risk being blacklisted.
Internal Server Error 500 or 200 + error:InternalServerError 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 200 + error:
DeviceMessageRate
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.
Connection Draining N/A CONNECTION_DRAINING The message couldn't be processed because the connection is draining. This happens because periodically, XMPP (CCS) needs to close down a connection to perform load balancing. Retry the message over another XMPP connection.