Send messages to device groups on C++

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:

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

  2. 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.

Optionally, Android client apps can manage device groups from the client side.

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: 

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
Authorization:key=API_KEY
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["4", "8", "15", "16", "23", "42"]
}

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: 

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
Authorization:key=API_KEY
project_id:SENDER_ID
{}

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.

HTTP POST request

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

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["51"]
}

Response format

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

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

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 POST Request 

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

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: 

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

When a message fails to be delivered to one or more of the registration tokens associated with a notification_key, the app server should retry with backoff between retries.

If the server attempts to send a message to a device group that has no members, the response looks like the following, with 0 success and 0 failure: 

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

Device Group XMPP Message 

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</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: 

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

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: 

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

When FCM connection server fails to deliver to all devices in the group. App server will receive a nack response.

For the full list of message options, see the reference information for your chosen connection server protocol, HTTP or XMPP.

Sending upstream messages to device groups

Client apps can send messages upstream to device groups by targeting messages to the appropriate notification key in the to field.

The following call to FCM sends an upstream message to a notification key.

::firebase::messaging::Message message;
message.to = notification_key;
message.message_id = a_unique_message_id;
message.data["hello"] = "world";
::firebase::messaging::Send(message);