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 Content-Type
:application/json
for JSON;application/x-www-form-urlencoded;charset=UTF-8
for plain text. IfContent-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..." }
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®istration_id=42
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.
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 forregistration_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 ofregistration_ids
passed in the request (using the same index).
- If
- 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.
- If it is
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.
- If second line starts with
- 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).
- If it is
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