To address or "target" a message, the app
server must set the to
key with one of these values:
- Topic name
- Device registration token
- Device group name
To these targets, you can send notification messages with predefined fields, or custom data messages; see Message types for more information. Examples in this page show how to send data messages in HTTP and XMPP protocols.
Send messages to specific devices
To send messages to specific devices, set the to
key to the registration
token for the specific app instance. See the client setup information for your
platform to learn more about registration tokens.
HTTP POST request
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
HTTP response
{ "multicast_id": 108, "success": 1, "failure": 0, "canonical_ids": 0, "results": [ { "message_id": "1:08" } ] }
XMPP message
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
XMPP response
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
The XMPP connection server provides some other options for responses. See Server response format.
For the full list of message options available when sending downstream messages to client app, see the reference information for your chosen connection server protocol, HTTP or XMPP.
Send messages to topics
From the server side, sending messages to a Firebase Cloud Messaging topic is very similar to
sending messages to an individual device or to a user group. The app
server sets the to
key with a value like /topics/yourTopic
.
Developers can
choose any topic name that matches the regular expression:
"/topics/[a-zA-Z0-9-_.~%]+"
.
To send to combinations of multiple topics, the app server sets the
condition
key to a boolean condition that specifies the
target topics. For example, to send messages to devices that subscribed
to TopicA
and either TopicB
or
TopicC
:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM first evaluates any conditions in parentheses, and then evaluates the expression from left to right. In the above expression, a user subscribed to any single topic does not receive the message. Likewise, a user who does not subscribe to TopicA does not receive the message. These combinations do receive it:
- TopicA and TopicB
- TopicA and TopicC
Conditions for topics support two operators per expression, and parentheses are supported.
For more detail about app server keys, see the reference information for your chosen connection server protocol, HTTP or XMPP. Examples in this page show how to send data messages to topics in both HTTP and XMPP.
HTTP POST request
Send to a single topic:
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"to": "/topics/foo-bar",
"data": {
"message": "This is a Firebase Cloud Messaging Topic Message!",
}
}
Send to devices subscribed to topics "dogs" or "cats":
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"condition": "'dogs' in topics || 'cats' in topics",
"data": {
"message": "This is a Firebase Cloud Messaging Topic Message!",
}
}
HTTP response
//Success example: { "message_id": "1023456" } //failure example: { "error": "TopicsMessageRateExceeded" }
XMPP message
Send to a single topic:
<message id="">
<gcm xmlns="google:mobile:data">
{
"to": "/topics/foo-bar",
"message_id": "m-1366082849205" ,
"data": {
"message":"This is a Firebase Cloud Messaging Topic Message!"
}
}
</gcm>
</message>
Send to devices subscribed to topics "dogs" or "cats":
<message id="">
<gcm xmlns="google:mobile:data">
{
"condition": "'dogs' in topics || 'cats' in topics",
"data": {
"message": "This is a Firebase Cloud Messaging Topic Message!",
}
}
</gcm>
</message>
XMPP response
//Success example: { "message_id": "1023456" } //failure example: { "error": "TopicsMessageRateExceeded" }
Expect up to 30 seconds of delay before the FCM Connection Server returns a success or failure response to the topic send requests. Make sure to set the app server's timeout value in the request accordingly.
For the full list of message options, see the reference information for your chosen connection server protocol, HTTP or XMPP.
Send 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.
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!", } }
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" ] }
In the case of failure, the response has HTTP code 503 and no JSON
body. 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.
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>
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.