Messaging with XMPP

Device-to-device FCM messaging over an XMPP connection using node-xcs and the Firebase Admin SDK for sending.

Prerequisites

  • @react-native-firebase/app and @react-native-firebase/messaging installed (npm install --save @react-native-firebase/app @react-native-firebase/messaging or yarn add @react-native-firebase/app @react-native-firebase/messaging), then rebuild native apps (cd ios && pod install on iOS). From v26, New Architecture is required for packages with a native bridge.
  • Native Firebase config completed per Getting Started (Android google-services.json, iOS GoogleService-Info.plist, Expo config plugin, or React Native CLI setup).
  • On iOS, complete iOS Messaging Setup (Push Notifications, Background Modes, APNs) before expecting delivery.
  • A custom XMPP server (for example the node-xcs npm package) and a Node.js environment with firebase-admin if you follow the server samples below.
  • sendMessage() is Android only. Calling it on iOS throws Error('getMessaging().sendMessage() is only supported on Android devices.') in JavaScript before any native call.

Introduction

This is a reference for using the Firebase Messaging service to send and receive messages directly between devices. Although methods (for example sendMessage()) are provided for sending and receiving messages, additional configuration is needed for direct messaging from devices.

A custom solution is only required if you plan to exchange messages directly between devices (including the message sender device). Configure a solution from this article before expecting device-to-device send/receive to work.

The following describes how to set up a server to handle messages, including:

  • A custom XMPP server with XCS for receiving messages.
  • Firebase Admin for sending messages.

Flow:

  1. Send a message from a client device (sendMessage, Android).
  2. Intercept using a custom XMPP server.
  3. Push the message to Firebase using firebase-admin.
  4. Receive the message and acknowledge on other connected devices.

Why can't I send and receive messages?

A common instance involves an implementation similar to the following.

js
import {
  getMessaging,
  onMessage,
  onMessageSent,
  onSendError,
  sendMessage,
} from '@react-native-firebase/messaging';

const messaging = getMessaging();

onMessage(messaging, message => {
  console.log('Received a message', message);
});

onMessageSent(messaging, messageId => {
  console.log('Sent a message', messageId);
});

onSendError(messaging, error => {
  // `error` is a SendErrorEvent: { messageId, error } (RN-only; no firebase-js-sdk modular equivalent).
  console.log('Received an Error', error.messageId, error.error);
});

// Android only. On iOS this throws Error in JavaScript (not a native reject).
sendMessage(messaging, {
  data: {
    foo: 'bar',
  },
});

SendErrorEvent is the React Native Firebase type for the onSendError callback payload (messageId plus a native Firebase error).

Although correct for the client API surface, none of the listeners will acknowledge a message or error without a server that bridges FCM and your devices.

Permissions are limited on the client, so an additional solution is required to communicate between FCM and any connected devices.

How do I receive messages?

Deploy a custom server based, for example, on Node XCS.

Below is an example of how to configure a custom XMPP server using node-xcs.

js
// codeblock-ignore: server-side sample that requires the node-xcs package
const Sender = require('node-xcs').Sender;

async function operation() {
  return () => {
    console.log('Listening >>>');

    // Enter firebase credentials here. {SenderID, ServerKey}
    var xcs = new Sender('XXXXXXXX', 'XXXXXXXX');

    xcs.start();

    xcs.on('message', function (messageId, from, data, category) {
      console.log('received message', messageId, from, data, category);
    });

    xcs.on('receipt', function (messageId, from, data, category) {
      console.log('received receipt', arguments);
    });

    xcs.on('error', e => console.warn('XMPP error.', e));
  };
}

async function app() {
  await operation();
}

app();

How do I send messages?

For sending messages from the server, use the Firebase Admin SDK.

js
// codeblock-ignore: server-side sample that requires the firebase-admin package
const admin = require('firebase-admin');
const serviceAccount = require('./service-account.json');

(async () => {
  admin.initializeApp({
    credential: admin.credential.cert(serviceAccount),
    databaseURL: 'XXXXXXXX',
  });

  await admin.messaging().send({
    token: 'XXXXXXX',
    data: {
      foo: 'bar',
    },
  });
})();