Implementing an HTTP Connection Server

This document describes the Google Cloud Messaging (GCM) HTTP connection server. Connection servers are the Google-provided servers that take messages from the application server and send them to the device.

See the Server Reference for a list of all the message parameters and which connection server(s) supports them.

Authentication

To send a message, the application server issues a POST request. For example:

https://gcm-http.googleapis.com/gcm/send

A message request is made of 2 parts: HTTP header and HTTP body.

The HTTP header must contain the following headers:

• Authorization: key=YOUR_SERVER_KEY
  Starting from September 2016, you can create new server keys only in the Firebase Console using the Cloud Messaging tab of the Settings panel. Existing projects that need to create a new server key can be imported in the Firebase console without affecting their existing configuration.
• Content-Type: application/json for JSON; application/x-www-form-urlencoded;charset=UTF-8 for plain text. If Content-Type is omitted, the format is assumed to be plain text.

For example:

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

The HTTP body content depends on whether you're using JSON or plain text. See the Server Reference for a list of all the parameters your JSON or plain text message can contain.

Checking the validity of a server key

If you receive authentication errors when sending messages, check the validity of your server key. For example, on Android, run the following command:

# server_key=YOUR_SERVER_KEY

# curl --header "Authorization: key=$server_key" \
       --header Content-Type:"application/json" \
       https://gcm-http.googleapis.com/gcm/send \
       -d "{\"registration_ids\":[\"ABC\"]}"

If you receive a 401 HTTP status code, your server key is not valid. Otherwise you should see something like this:

{"multicast_id":6782339717028231855,"success":0,"failure":1,
"canonical_ids":0,"results":[{"error":"InvalidRegistration"}]}

If you want to confirm the validity of a registration token, you can do so by replacing "ABC" with the registration token.

Request Format

This section shows you how to format requests for both JSON and plain text. See the Server Reference for a complete list of the fields you can include in a request.

Send-to-sync

Here is the smallest possible request (a message without any parameters and just one recipient) using JSON:

{ "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..." }

And here the same example using plain text:

registration_id=42

Message with payload — notification message

Here is a notification message:

{ "notification": {
    "title": "Portugal vs. Denmark",
    "text": "5 to 1"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

You can have messages with both notification and data payloads. See the Server Reference for supported keys in notification payloads. For more information about notification message and data message options, see Payload.

Message with payload — data message

Here is a message with a data payload:

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

Here is a message with all optional fields set:

{ "collapse_key": "score_update",
  "time_to_live": 108,
  "data": {
    "score": "4x8",
    "time": "15:16.2342"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

And here is the same message using plain-text format:

collapse_key=score_update&time_to_live=108&data.score=4x8&data.time=15:16.2342&registration_id=42
  

If your organization has a firewall that restricts the traffic to or from the Internet, you need to configure it to allow connectivity with GCM in order for your GCM client apps to receive messages. The ports to open are: 5228, 5229, and 5230. GCM typically only uses 5228, but it sometimes uses 5229 and 5230. GCM doesn't provide specific IPs, so you should allow your firewall to accept outgoing connections to all IP addresses contained in the IP blocks listed in Google's ASN of 15169.

Response format

There are two possible outcomes when trying to send a message:

• The message is processed successfully. The HTTP response has a 200 status, and the body contains more information about the status of the message.
• GCM rejects the request. The HTTP response contains a non-200 status code (such as 400, 401 or 5xx).

When a JSON request is successful (HTTP status code 200), the JSON object returned contains the Downstream HTTP message response body. Log the message ID value for all messages, in case you need to troubleshoot the message with Google support or through GCM diagnostics.

If the value of failure and canonical_ids is 0, it's not necessary to parse the remainder of the response. Otherwise, we recommend that you iterate through the results field and do the following for each object in that list:

• If message_id is set, check for registration_id:
  • If registration_id is set, replace the original ID with the new value (canonical ID) in your server database. Note that the original ID is not part of the result, so you need to obtain it from the list of registration_ids passed in the request (using the same index).
• Otherwise, get the value of error:
  • If it is Unavailable, you could retry to send it in another request.
  • If it is NotRegistered, you should remove the registration ID from your server database because the application was uninstalled from the device, or the client app isn't configured to receive messages.
  • Otherwise, there is something wrong in the registration token passed in the request; it is probably a non-recoverable error that will also require removing the registration from the server database. See Downstream message error response codes for all possible error values.

When a plain-text request is successful (HTTP status code 200), the response body contains 1 or 2 lines in the form of key/value pairs. The first line is always available and its content is either id=ID of sent message or Error=GCM error code. The second line, if available, has the format of registration_id=canonical ID. The second line is optional, and it can only be sent if the first line is not an error. We recommend handling the plain-text response in a similar way as handling the JSON response:

• If first line starts with id, check second line:
  • If second line starts with registration_id, gets its value and replace the registration tokens in your server database.
• Otherwise, get the value of Error:
  • If it is NotRegistered, remove the registration token from your server database.
  • Otherwise, there is probably a non-recoverable error (Note: Plain-text requests will never return Unavailable as the error code, they would have returned a 500 HTTP status instead).

Example responses

This section shows a few examples of responses indicating messages that were processed successfully. See Request Format for the requests these responses are based on.

Here is a simple case of a JSON message successfully sent to one recipient without canonical IDs in the response:

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "canonical_ids": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

Or if the request was in plain-text format:

id=1:08

Here are JSON results for 6 recipients (IDs 4, 8, 15, 16, 23, and 42 respectively) with 3 messages successfully processed, 1 canonical registration token returned, and 3 errors:

{ "multicast_id": 216,
  "success": 3,
  "failure": 3,
  "canonical_ids": 1,
  "results": [
    { "message_id": "1:0408" },
    { "error": "Unavailable" },
    { "error": "InvalidRegistration" },
    { "message_id": "1:1516" },
    { "message_id": "1:2342", "registration_id": "32" },
    { "error": "NotRegistered"}
  ]
}

In this example:

• First message: success, not required.
• Second message: should be resent (to registration token 8).
• Third message: had an unrecoverable error (maybe the value got corrupted in the database).
• Fourth message: success, nothing required.
• Fifth message: success, but the registration token should be updated in the server database (from 23 to 32).
• Sixth message: registration token (42) should be removed from the server database because the application was uninstalled from the device.

Or if just the third message above was sent using plain-text format:

Error=InvalidRegistration

If the fifth message above was also sent using plain-text format:

id=1:2342
registration_id=32