Send messages to device groups on Android

Device group messaging allows you to add multiple devices to a single group.
This is similar to topic messaging, but includes authentication to ensure
that group membership is managed only by your
servers. For example, if you want to send different messages to different phone models, your
servers can add/remove registrations to the appropriate groups and send the appropriate
message to each group. Device group messaging differs from topic messaging in that it involves
managing device groups from your servers instead of directly within your application.

You can use device group messaging via the
legacy
XMPP or
HTTP protocols on your app server.
Firebase Admin SDK for Node.js
based on the
legacy protocols also provide device group messaging capabilities.
The maximum number of members allowed for a
notification key is 20.

Managing device groups

Before sending messages to a device group, you must:

Obtain registration tokens for each device you want to add
to the group.

Create the notification_key, which identifies
the device group by mapping a particular group (typically a
user) to all of the group's associated registration tokens.
You can create notification keys on the app server or on
Android client apps.

Basic management of device groups — creating and removing groups,
and adding or removing devices — is usually performed via the app
server. See the legacy
HTTP protocol reference for a list of supported keys.

Managing device groups on the app server

Creating a device group

To create a device group, send a POST request that provides a name
for the group, and a list of registration tokens for the devices.
FCM returns a new notification_key
that represents the device group.

HTTP POST request

Send a request like the following to
https://fcm.googleapis.com/fcm/notification:

The notification_key_name is a name or identifier
(e.g., it can be a username) that is unique to a given group. The
notification_key_name and
notification_key are unique to a group of registration
tokens. It is important that notification_key_name is
unique per client app if you have multiple client apps for the same
sender ID.
This ensures that messages only go to the intended target app.

Response format

A successful request returns a notification_key like
the following:

{
"notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Save the notification_key and the corresponding
notification_key_name to use in subsequent operations.

Retrieving a notification key

If you need to retrieve an existing notification key, use the
notification_key_name in a GET request as shown:

For each GET request for a given notification key name, the server
returns a unique encoded string. Though each string may appear to be
a different key, it is actually a valid `notification_key` value.

Adding and removing devices from a device group

To add or remove devices from an existing group, send a POST
request with the operation parameter set to
add or remove, and provide the
registration tokens for addition or removal.

If you remove all existing registration tokens from a device group,
FCM deletes the device group.

HTTP POST request

For example, to add a
device with the registration ID 51 to appUser-Chris, you would send
this request:

A successful request to either add or remove a device returns a
notification_key like the following:

{
"notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Note:notification_key_name is not required
for adding/removing registration tokens, but including it protects you against
accidentally using the incorrect notification_key.

Managing device groups on Android client apps

Managing device groups on the client is useful for cases where a
server is unavailable. To create a device group on the client, the
device must have at least one Google account. Note that the process
for creating a notification key on the client is significantly
different from the server-side process described above.

Add or remove devices from groups

Build an HTTP POST request to
https://fcm.googleapis.com/fcm/googlenotification
to add/remove registration tokens to/from a group. The request
header needs to have project_id set to the sender ID and
Content-Type set to JSON.

Client requests take only a single registration token for
each operation.

Add to group

An add operation requires the following keys:
operation set to add,
id_token set to the idToken obtained
above, notification_key_name and
registration_ids. The userEmail variable,
as shown below, can be derived from the value of
accounts[0].name. The client is authorized to manage
only groups mapped to this email/account.

Sending downstream messages to device groups

Sending messages to a device group is very similar to sending
messages to an individual device. Set the to parameter
to the unique notification key for the device group. See
Message types for details on
payload support. Examples in this page show how to send data
messages to device groups in HTTP and XMPP protocols.

Device Group HTTP Response

Here is an example of "success"— the notification_key
has 2 registration tokens associated with it, and the message was
successfully sent to both of them:

{
"success": 2,
"failure": 0
}

Here is an example of "partial success" — the
notification_key has 3 registration tokens associated
with it. The message was successfully sent to 1 of the registration
tokens only. The response message lists the registration tokens
that failed to receive the message:

Device Group XMPP Response

When the message is sent to any one of the devices in the group
successfully, the XMPP connection server responds with an ACK. If
all messages sent to all devices in the group fail, XMPP connection
server responds with a NACK.

Here is an example of "success" — the notification_key
has 3 registration tokens associated with it, and the message was
successfully sent to all of them:

Here is an example of "partial success" — the
notification_key has 3 registration tokens associated
with it. The message was successfully sent to 1 of the registration
tokens only. The response message lists the registration tokens
that failed to receive the message: