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.

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
  • 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..."
}

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
  

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

Send feedback about...

Cloud Messaging
Cloud Messaging