About Firebase Cloud Messaging Server

The server side of Firebase Cloud Messaging consists of two components:

The app server or trusted server environment sends message requests to the FCM servers, which then sends messages to client apps running on users' devices.

For more information about implementing the client side, see the client guide for your platform: iOS, Android, or Web.

Role of the trusted server environment

Before you can write client apps that use Firebase Cloud Messaging, you must have a server environment that meets the following criteria:

  • Able to communicate with your client.
  • Able to send properly formatted message requests to the FCM server.
  • Able to handle requests and resend them using exponential back-off.
  • Able to securely store the server key and client registration tokens. Note: never include the server key in any client code.
  • For XMPP, the server must be able to generate message IDs to uniquely identify each message it sends (FCM HTTP connection server generates message IDs and returns them in the response). XMPP message IDs should be unique per sender ID.

You'll need to decide on a way to interact with FCM servers: either using the Admin SDK or the raw protocols. Among the raw protocol options, the FCM HTTP v1 API is the most up to date, with more secure authorization and flexible cross-platform messaging capabilities. The legacy HTTP and XMPP server protocols area also available. Note that if you want to use upstream messaging from your client applications, you must use XMPP. For a more detailed discussion of this, see FCM Server Protocols.

FCM Server Protocols

Currently FCM provides these raw server protocols:

Your app server can use these protocols separately or in tandem. Because it is the most up-to-date and most flexible for sending messages to multiple platforms, the FCM HTTP v1 API is recommended wherever feasible. If your requirements include upstream messaging from devices to the server, you'll need to implement the XMPP protocol.

XMPP messaging differs from HTTP messaging in the following ways:

  • Upstream/Downstream messages
    • HTTP: Downstream only, cloud-to-device.
    • XMPP: Upstream and downstream (device-to-cloud, cloud-to-device).
  • Messaging (synchronous or asynchronous)
    • HTTP: Synchronous. App servers send messages as HTTP POST requests and wait for a response. This mechanism is synchronous and blocks the sender from sending another message until the response is received.
    • XMPP: Asynchronous. App servers send/receive messages to/from all their devices at full line speed over persistent XMPP connections. The XMPP connection server sends acknowledgment or failure notifications (in the form of special ACK and NACK JSON-encoded XMPP messages) asynchronously.
  • JSON
    • HTTP: JSON messages sent as HTTP POST.
    • XMPP: JSON messages encapsulated in XMPP messages.
  • Plain Text
    • HTTP: Plain Text messages sent as HTTP POST.
    • XMPP: Not supported.
  • Multicast downstream send to multiple registration tokens.
    • HTTP: Supported in JSON message format.
    • XMPP: Not supported.

Implementing the HTTP server protocol

To send a message, the app server issues a POST request with an HTTP header and an HTTP body comprised of JSON key value pairs. For details on the header and body options, see Build App Server Send Requests

Implementing the XMPP server protocol

The JSON payload for FCM messages is similar to the HTTP protocol, with these exceptions:

  • There is no support for multiple recipients.
  • FCM adds the field message_id, which is required. This ID uniquely identifies the message in an XMPP connection. The ACK or NACK from FCM uses the message_id to identify a message sent from app servers to FCM. Therefore, it's important that this message_id not only be unique (per sender ID), but always present.
  • XMPP uses the server key to authorize a persistent connection to FCM. See Authorize Send Requests for more information.

In addition to regular FCM messages, control messages are sent, indicated by the message_type field in the JSON object. The value can be either 'ack' or 'nack', or 'control' (see formats below). Any FCM message with an unknown message_type can be ignored by your server.

For each device message your app server receives from FCM, it needs to send an ACK message. It never needs to send a NACK message. If you don't send an ACK for a message, FCM resends it the next time a new XMPP connection is established, unless the message expires first.

FCM also sends an ACK or NACK for each server-to-device message. If you do not receive either, it means that the TCP connection was closed in the middle of the operation and your server needs to resend the messages. See Flow Control for details.

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

Request format

Message with payload — notification message

Here is an XMPP stanza for a notification message:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
}

  }
  </gcm>
</message>

Message with payload — data message

Here is an XMPP stanza containing the JSON message from an app server to FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
      "delivery_receipt_requested": true/false
  }
  </gcm>
</message>

Response format

An FCM response can have three possible forms. The first one is a regular 'ack' message. But when the response contains an error, there are 2 different forms the message can take, described below.

ACK message

Here is an XMPP stanza containing the ACK/NACK message from FCM to the app server:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

NACK message

A NACK error is a regular XMPP message in which the message_type status message is "nack". A NACK message contains:

  • A NACK error code.
  • A NACK error description.

Below are some examples.

Bad registration:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

Invalid JSON:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Device Message Rate Exceeded:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

See the Server Reference for a complete list of the NACK error codes. Unless otherwise indicated, a NACKed message should not be retried. Unexpected NACK error codes should be treated the same as INTERNAL_SERVER_ERROR.

Stanza error

You can also get a stanza error in certain cases. A stanza error contains:

  • Stanza error code.
  • Stanza error description (free text).

For example:

<message id="3" type="error" to="123456789@gcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Control messages

Periodically, FCM needs to close down a connection to perform load balancing. Before it closes the connection, FCM sends a CONNECTION_DRAINING message to indicate that the connection is being drained and will be closed soon. "Draining" refers to shutting off the flow of messages coming into a connection, but allowing whatever is already in the pipeline to continue. When you receive a CONNECTION_DRAINING message, you should immediately begin sending messages to another FCM connection, opening a new connection if necessary. You should, however, keep the original connection open and continue receiving messages that may come over the connection (and ACKing them)—FCM handles initiating a connection close when it is ready.

The CONNECTION_DRAINING message looks like this:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING is currently the only control_type supported.

Receive delivery receipts

For Android and Chrome client apps, you can get delivery receipts (sent from FCM to your app server) when a device confirms that it received a message sent by FCM.

To enable this feature, the message your app server sends to FCM must include the field delivery_receipt_requested. When this field is set to true, FCM sends a delivery receipt when a device confirms that it received a particular message.

Here is an XMPP stanza containing a JSON message with "delivery_receipt_requested" set to true:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",
      "message_id":"m-1366082849205"
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
      "delivery_receipt_requested": true
  }
  </gcm>
</message>

Here is an example of the delivery receipt that FCM sends to tell your app server that a device received a message that FCM sent it:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "category":"com.example.yourapp", // to know which app sent it
      "data":
      {
         “message_status":"MESSAGE_SENT_TO_DEVICE",
         “original_message_id”:”m-1366082849205”
         “device_registration_id”: “REGISTRATION_ID”
      },
      "message_id":"dr2:m-1366082849205",
      "message_type":"receipt",
      "from":"gcm.googleapis.com"
  }
  </gcm>
</message>

Note the following:

  • The "message_type" is set to "receipt".
  • The "message_status" is set to "MESSAGE_SENT_TO_DEVICE", indicating that the device received the message. Notice that in this case, "message_status" is not a field but rather part of the data payload.
  • The receipt message ID consists of the original message ID, but with a dr2: prefix. Your app server must use the same connection to send an ACK back with this ID, which in this example is dr2:m-1366082849205.
  • The original message ID, the device registration token, and the status are inside the "data" field.
  • If the connection between FCM and the device is poor, Firebase Cloud Messaging may send multiple, duplicate delivery receipts. You can safely ignore such duplicates.

Flow control

Every message sent to FCM receives either an ACK or a NACK response. Messages that haven't received one of these responses are considered pending. If the pending message count reaches 100, the app server should stop sending new messages and wait for FCM to acknowledge some of the existing pending messages as illustrated in figure 1:

Figure 1. Message/ack flow.

Conversely, to avoid overloading the app server, FCM stops sending if there are too many unacknowledged messages. Therefore, the app server should "ACK" upstream messages, received from the client application via FCM, as soon as possible to maintain a constant flow of incoming messages. The aforementioned pending message limit doesn't apply to these ACKs. Even if the pending message count reaches 100, the app server should continue sending ACKs for messages received from FCM to avoid blocking delivery of new upstream messages.

ACKs are only valid within the context of one connection. If the connection is closed before a message can be ACKed, the app server should wait for FCM to resend the upstream message before ACKing it again. Similarly, all pending messages for which an ACK/NACK was not received from FCM before the connection was closed should be sent again.

Send feedback about...

Need help? Visit our support page.