Sending upstream messages on Android

If your app server implements the XMPP Connection Server protocol, it can receive upstream messages from a user's device to the cloud. To initiate an upstream message, the client app sends a request containing the following:

  • The address of the receiving app server in the format SENDER_ID@fcm.googleapis.com.
  • A message ID that should be unique for each sender ID.
  • The message data comprising the key-value pairs of the message's payload.

When it receives this data, FCM builds an XMPP stanza to send to the app server, adding some additional information about the sending device and app.

Send an upstream message from an Android client app

Your Android app can send an upstream message using FirebaseMessaging.send:

Kotlin+KTX 

val fm = Firebase.messaging
fm.send(
    remoteMessage("$SENDER_ID@fcm.googleapis.com") {
        setMessageId(messageId.toString())
        addData("my_message", "Hello World")
        addData("my_action", "SAY_HELLO")
    },
)
MainActivity.kt

Java 

FirebaseMessaging fm = FirebaseMessaging.getInstance();
fm.send(new RemoteMessage.Builder(SENDER_ID + "@fcm.googleapis.com")
        .setMessageId(Integer.toString(messageId))
        .addData("my_message", "Hello World")
        .addData("my_action","SAY_HELLO")
        .build());
MainActivity.java

Handle upstream message callbacks

With FirebaseMessaging, you can implement the callbacks onMessageSent and onSendError to check the status of upstream messages. In error cases, onSendError returns a SendException with an error code. For example, if the client attempts to send more messages after the 20-message limit is reached, it returns SendException#ERROR_TOO_MANY_MESSAGES.

In cases where the device is offline or the FCM service is unavailable to forward upstream messages to your server, Android client app instances can accumulate a maximum of 20 pending messages. If such messages expire before FCM can successfully send them, onSendError returns SendException#ERROR_TTL_EXCEEDED.

To optimize network usage, FCM batches responses to onMessageSent and onSendError, so the acknowledgement may not be immediate for each message.

Receive XMPP messages on the app server

When FCM receives an upstream messaging call from a client app, it generates the necessary XMPP stanza for sending the upstream message. FCM adds the category and from fields, and then sends a stanza like the following to the app server:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "category":"com.example.yourapp", // to know which app sent it
      "data":
      {
          "hello":"world",
      },
      "message_id":"m-123",
      "from":"REGID"
  }
  </gcm>
</message>

Sending an ACK message

In response to an upstream message like the above, the app server must use the same connection to send an ACK message containing the unique message ID. If FCM does not receive an ACK, it may retry sending the message to the app server.

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

See the XMPP Connection Server Reference for more information about upstream message syntax.