Using the Firebase Admin SDK or FCM app server protocols, you can build message requests and send them to these types of targets:
- Topic name
- Condition
- Device registration token
- Device group name (protocol only)
You can send messages with a notification payload made up of predefined fields, a data payload of your own user-defined fields, or a message containing both types of payload. See Message types for more information.
Examples in this page show how to send notification messages using the Firebase Admin SDK (which has support for Node , Java , Python , C# , and Go ) and the v1 HTTP protocol .
Send messages to specific devices
To send to a single, specific device, pass the device's registration token as shown. See the client setup information for your platform to learn more about registration tokens.
Node.js
// This registration token comes from the client FCM SDKs.
const
registrationToken
=
'YOUR_REGISTRATION_TOKEN'
;
const
message
=
{
data
:
{
score
:
'850'
,
time
:
'2:45'
},
token
:
registrationToken
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
Java
// This registration token comes from the client FCM SDKs.
String
registrationToken
=
"YOUR_REGISTRATION_TOKEN"
;
// See documentation on defining a message payload.
Message
message
=
Message
.
builder
()
.
putData
(
"score"
,
"850"
)
.
putData
(
"time"
,
"2:45"
)
.
setToken
(
registrationToken
)
.
build
();
// Send a message to the device corresponding to the provided
// registration token.
String
response
=
FirebaseMessaging
.
getInstance
().
send
(
message
);
// Response is a message ID string.
System
.
out
.
println
(
"Successfully sent message: "
+
response
);
Python
# This registration token comes from the client FCM SDKs.
registration_token
=
'YOUR_REGISTRATION_TOKEN'
# See documentation on defining a message payload.
message
=
messaging
.
Message
(
data
=
{
'score'
:
'850'
,
'time'
:
'2:45'
,
},
token
=
registration_token
,
)
# Send a message to the device corresponding to the provided
# registration token.
response
=
messaging
.
send
(
message
)
# Response is a message ID string.
print
(
'Successfully sent message:'
,
response
)
Go
// Obtain a messaging.Client from the App.
ctx
:=
context
.
Background
()
client
,
err
:=
app
.
Messaging
(
ctx
)
if
err
!=
nil
{
log
.
Fatalf
(
"error getting Messaging client: %v\n"
,
err
)
}
// This registration token comes from the client FCM SDKs.
registrationToken
:=
"YOUR_REGISTRATION_TOKEN"
// See documentation on defining a message payload.
message
:=
& messaging
.
Message
{
Data
:
map
[
string
]
string
{
"score"
:
"850"
,
"time"
:
"2:45"
,
},
Token
:
registrationToken
,
}
// Send a message to the device corresponding to the provided
// registration token.
response
,
err
:=
client
.
Send
(
ctx
,
message
)
if
err
!=
nil
{
log
.
Fatalln
(
err
)
}
// Response is a message ID string.
fmt
.
Println
(
"Successfully sent message:"
,
response
)
C#
// This registration token comes from the client FCM SDKs.
var
registrationToken
=
"YOUR_REGISTRATION_TOKEN"
;
// See documentation on defining a message payload.
var
message
=
new
Message
()
{
Data
=
new
Dictionary<string
,
string
> ()
{
{
"score"
,
"850"
},
{
"time"
,
"2:45"
},
},
Token
=
registrationToken
,
};
// Send a message to the device corresponding to the provided
// registration token.
string
response
=
await
FirebaseMessaging
.
DefaultInstance
.
SendAsync
(
message
);
// Response is a message ID string.
Console
.
WriteLine
(
"Successfully sent message: "
+
response
);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
cURL command:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"notification":{
"title":"FCM Message",
"body":"This is an FCM Message"
},
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
On success, each send method returns a message ID. The Firebase
Admin SDK
returns
the ID string in the format projects/{project_id}/messages/{message_id}
.
The HTTP protocol response is a single JSON key:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Send one message to multiple devices
The Admin FCM SDKs allow you to multicast a message to a list of device registration tokens. You can use this feature when you need to send the same message to a large number of devices. You can specify up to 500 device registration tokens per invocation.
The return value includes a list of tokens that corresponds to the order of the input tokens. This is useful when you want to check which tokens resulted in errors and then handle them appropriately .
Node.js
// These registration tokens come from the client FCM SDKs.
const
registrationTokens
=
[
'YOUR_REGISTRATION_TOKEN_1'
,
// …
'YOUR_REGISTRATION_TOKEN_N'
,
];
const
message
=
{
data
:
{
score
:
'850'
,
time
:
'2:45'
},
tokens
:
registrationTokens
,
};
getMessaging
().
sendEachForMulticast
(
message
)
.
then
((
response
)
=
>
{
if
(
response
.
failureCount
>
0
)
{
const
failedTokens
=
[];
response
.
responses
.
forEach
((
resp
,
idx
)
=
>
{
if
(
!
resp
.
success
)
{
failedTokens
.
push
(
registrationTokens
[
idx
]);
}
});
console
.
log
(
'List of tokens that caused failures: '
+
failedTokens
);
}
});
Java
// These registration tokens come from the client FCM SDKs.
List<String>
registrationTokens
=
Arrays
.
asList
(
"YOUR_REGISTRATION_TOKEN_1"
,
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage
message
=
MulticastMessage
.
builder
()
.
putData
(
"score"
,
"850"
)
.
putData
(
"time"
,
"2:45"
)
.
addAllTokens
(
registrationTokens
)
.
build
();
BatchResponse
response
=
FirebaseMessaging
.
getInstance
().
sendEachForMulticast
(
message
);
if
(
response
.
getFailureCount
()
>
0
)
{
List<SendResponse>
responses
=
response
.
getResponses
();
List<String>
failedTokens
=
new
ArrayList
<> ();
for
(
int
i
=
0
;
i
<
responses
.
size
();
i
++
)
{
if
(
!
responses
.
get
(
i
).
isSuccessful
())
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens
.
add
(
registrationTokens
.
get
(
i
));
}
}
System
.
out
.
println
(
"List of tokens that caused failures: "
+
failedTokens
);
}
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens
=
[
'YOUR_REGISTRATION_TOKEN_1'
,
# ...
'YOUR_REGISTRATION_TOKEN_N'
,
]
message
=
messaging
.
MulticastMessage
(
data
=
{
'score'
:
'850'
,
'time'
:
'2:45'
},
tokens
=
registration_tokens
,
)
response
=
messaging
.
send_each_for_multicast
(
message
)
if
response
.
failure_count
> 0
:
responses
=
response
.
responses
failed_tokens
=
[]
for
idx
,
resp
in
enumerate
(
responses
):
if
not
resp
.
success
:
# The order of responses corresponds to the order of the registration tokens.
failed_tokens
.
append
(
registration_tokens
[
idx
])
print
(
f
'List of tokens that caused failures:
{
failed_tokens
}
'
)
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens
:=
[]
string
{
"YOUR_REGISTRATION_TOKEN_1"
,
// ...
"YOUR_REGISTRATION_TOKEN_n"
,
}
message
:=
& messaging
.
MulticastMessage
{
Data
:
map
[
string
]
string
{
"score"
:
"850"
,
"time"
:
"2:45"
,
},
Tokens
:
registrationTokens
,
}
br
,
err
:=
client
.
SendEachForMulticast
(
context
.
Background
(),
message
)
if
err
!=
nil
{
log
.
Fatalln
(
err
)
}
if
br
.
FailureCount
>
0
{
var
failedTokens
[]
string
for
idx
,
resp
:=
range
br
.
Responses
{
if
!
resp
.
Success
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens
=
append
(
failedTokens
,
registrationTokens
[
idx
])
}
}
fmt
.
Printf
(
"List of tokens that caused failures: %v\n"
,
failedTokens
)
}
C#
// These registration tokens come from the client FCM SDKs.
var
registrationTokens
=
new
List<string>
()
{
"YOUR_REGISTRATION_TOKEN_1"
,
// ...
"YOUR_REGISTRATION_TOKEN_n"
,
};
var
message
=
new
MulticastMessage
()
{
Tokens
=
registrationTokens
,
Data
=
new
Dictionary<string
,
string
> ()
{
{
"score"
,
"850"
},
{
"time"
,
"2:45"
},
},
};
var
response
=
await
FirebaseMessaging
.
DefaultInstance
.
SendEachForMulticastAsync
(
message
);
if
(
response
.
FailureCount
>
0
)
{
var
failedTokens
=
new
List<string>
();
for
(
var
i
=
0
;
i
<
response
.
Responses
.
Count
;
i
++
)
{
if
(
!
response
.
Responses
[
i
].
IsSuccess
)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens
.
Add
(
registrationTokens
[
i
]);
}
}
Console
.
WriteLine
(
$"List of tokens that caused failures: {failedTokens}"
);
}
Send a list of messages
The Admin SDKs support sending a list of up to 500 messages. This feature can be used to build a customized set of messages and send them to different recipients, including topics or specific device registration tokens. For example, you can use this feature when you need to send different audiences slightly differentiated messages.
Node.js
// Create a list containing up to 500 messages.
const
messages
=
[];
messages
.
push
({
notification
:
{
title
:
'Price drop'
,
body
:
'5% off all electronics'
},
token
:
registrationToken
,
});
messages
.
push
({
notification
:
{
title
:
'Price drop'
,
body
:
'2% off all books'
},
topic
:
'readers-club'
,
});
getMessaging
().
sendEach
(
messages
)
.
then
((
response
)
=
>
{
console
.
log
(
response
.
successCount
+
' messages were sent successfully'
);
});
Java
// Create a list containing up to 500 messages.
List<Message>
messages
=
Arrays
.
asList
(
Message
.
builder
()
.
setNotification
(
Notification
.
builder
()
.
setTitle
(
"Price drop"
)
.
setBody
(
"5% off all electronics"
)
.
build
())
.
setToken
(
registrationToken
)
.
build
(),
// ...
Message
.
builder
()
.
setNotification
(
Notification
.
builder
()
.
setTitle
(
"Price drop"
)
.
setBody
(
"2% off all books"
)
.
build
())
.
setTopic
(
"readers-club"
)
.
build
()
);
BatchResponse
response
=
FirebaseMessaging
.
getInstance
().
sendEach
(
messages
);
// See the BatchResponse reference documentation
// for the contents of response.
System
.
out
.
println
(
response
.
getSuccessCount
()
+
" messages were sent successfully"
);
Python
# Create a list containing up to 500 messages.
messages
=
[
messaging
.
Message
(
notification
=
messaging
.
Notification
(
'Price drop'
,
'5
% o
ff all electronics'
),
token
=
registration_token
,
),
# ...
messaging
.
Message
(
notification
=
messaging
.
Notification
(
'Price drop'
,
'2
% o
ff all books'
),
topic
=
'readers-club'
,
),
]
response
=
messaging
.
send_each
(
messages
)
# See the BatchResponse reference documentation
# for the contents of response.
print
(
f
'
{
response
.
success_count
}
messages were sent successfully'
)
Go
// Create a list containing up to 500 messages.
messages
:=
[]
*
messaging
.
Message
{
{
Notification
:
& messaging
.
Notification
{
Title
:
"Price drop"
,
Body
:
"5% off all electronics"
,
},
Token
:
registrationToken
,
},
{
Notification
:
& messaging
.
Notification
{
Title
:
"Price drop"
,
Body
:
"2% off all books"
,
},
Topic
:
"readers-club"
,
},
}
br
,
err
:=
client
.
SendEach
(
context
.
Background
(),
messages
)
if
err
!=
nil
{
log
.
Fatalln
(
err
)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt
.
Printf
(
"%d messages were sent successfully\n"
,
br
.
SuccessCount
)
C#
// Create a list containing up to 500 messages.
var
messages
=
new
List<Message>
()
{
new
Message
()
{
Notification
=
new
Notification
()
{
Title
=
"Price drop"
,
Body
=
"5% off all electronics"
,
},
Token
=
registrationToken
,
},
new
Message
()
{
Notification
=
new
Notification
()
{
Title
=
"Price drop"
,
Body
=
"2% off all books"
,
},
Topic
=
"readers-club"
,
},
};
var
response
=
await
FirebaseMessaging
.
DefaultInstance
.
SendEachAsync
(
messages
);
// See the BatchResponse reference documentation
// for the contents of response.
Console
.
WriteLine
(
$"{response.SuccessCount} messages were sent successfully"
);
Send messages to topics
After you have created a topic, either by subscribing client app instances to the topic on the client side or via the server API , you can send messages to the topic. If this is your first time building send requests for FCM , see the guide to your server environment and FCM for important background and setup information.
In your sending logic on the backend, specify the desired topic name as shown:
Node.js
// The topic name can be optionally prefixed with "/topics/".
const
topic
=
'highScores'
;
const
message
=
{
data
:
{
score
:
'850'
,
time
:
'2:45'
},
topic
:
topic
};
// Send a message to devices subscribed to the provided topic.
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
Java
// The topic name can be optionally prefixed with "/topics/".
String
topic
=
"highScores"
;
// See documentation on defining a message payload.
Message
message
=
Message
.
builder
()
.
putData
(
"score"
,
"850"
)
.
putData
(
"time"
,
"2:45"
)
.
setTopic
(
topic
)
.
build
();
// Send a message to the devices subscribed to the provided topic.
String
response
=
FirebaseMessaging
.
getInstance
().
send
(
message
);
// Response is a message ID string.
System
.
out
.
println
(
"Successfully sent message: "
+
response
);
Python
# The topic name can be optionally prefixed with "/topics/".
topic
=
'highScores'
# See documentation on defining a message payload.
message
=
messaging
.
Message
(
data
=
{
'score'
:
'850'
,
'time'
:
'2:45'
,
},
topic
=
topic
,
)
# Send a message to the devices subscribed to the provided topic.
response
=
messaging
.
send
(
message
)
# Response is a message ID string.
print
(
'Successfully sent message:'
,
response
)
Go
// The topic name can be optionally prefixed with "/topics/".
topic
:=
"highScores"
// See documentation on defining a message payload.
message
:=
& messaging
.
Message
{
Data
:
map
[
string
]
string
{
"score"
:
"850"
,
"time"
:
"2:45"
,
},
Topic
:
topic
,
}
// Send a message to the devices subscribed to the provided topic.
response
,
err
:=
client
.
Send
(
ctx
,
message
)
if
err
!=
nil
{
log
.
Fatalln
(
err
)
}
// Response is a message ID string.
fmt
.
Println
(
"Successfully sent message:"
,
response
)
C#
// The topic name can be optionally prefixed with "/topics/".
var
topic
=
"highScores"
;
// See documentation on defining a message payload.
var
message
=
new
Message
()
{
Data
=
new
Dictionary<string
,
string
> ()
{
{
"score"
,
"850"
},
{
"time"
,
"2:45"
},
},
Topic
=
topic
,
};
// Send a message to the devices subscribed to the provided topic.
string
response
=
await
FirebaseMessaging
.
DefaultInstance
.
SendAsync
(
message
);
// Response is a message ID string.
Console
.
WriteLine
(
"Successfully sent message: "
+
response
);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
cURL command:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message": {
"topic" : "foo-bar",
"notification": {
"body": "This is a Firebase Cloud Messaging Topic Message!",
"title": "FCM Message"
}
}
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
To send a message to a combination
of topics,
specify a condition
, which is a boolean expression that specifies the
target topics. For example, the following condition will send messages to
devices that are 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:
-
TopicAandTopicB -
TopicAandTopicC
You can include up to five topics in your conditional expression.
To send to a condition:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const
condition
=
'\'stock-GOOG\' in topics || \'industry-tech\' in topics'
;
// See documentation on defining a message payload.
const
message
=
{
notification
:
{
title
:
'$FooCorp up 1.43% on the day'
,
body
:
'$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
condition
:
condition
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
Java
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String
condition
=
"'stock-GOOG' in topics || 'industry-tech' in topics"
;
// See documentation on defining a message payload.
Message
message
=
Message
.
builder
()
.
setNotification
(
Notification
.
builder
()
.
setTitle
(
"$GOOG up 1.43% on the day"
)
.
setBody
(
"$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
)
.
build
())
.
setCondition
(
condition
)
.
build
();
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String
response
=
FirebaseMessaging
.
getInstance
().
send
(
message
);
// Response is a message ID string.
System
.
out
.
println
(
"Successfully sent message: "
+
response
);
Python
# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition
=
"'stock-GOOG' in topics || 'industry-tech' in topics"
# See documentation on defining a message payload.
message
=
messaging
.
Message
(
notification
=
messaging
.
Notification
(
title
=
'$GOOG up 1.43
% o
n the day'
,
body
=
'$GOOG gained 11.80 points to close at 835.67, up 1.43
% o
n the day.'
,
),
condition
=
condition
,
)
# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response
=
messaging
.
send
(
message
)
# Response is a message ID string.
print
(
'Successfully sent message:'
,
response
)
Go
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition
:=
"'stock-GOOG' in topics || 'industry-tech' in topics"
// See documentation on defining a message payload.
message
:=
& messaging
.
Message
{
Data
:
map
[
string
]
string
{
"score"
:
"850"
,
"time"
:
"2:45"
,
},
Condition
:
condition
,
}
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response
,
err
:=
client
.
Send
(
ctx
,
message
)
if
err
!=
nil
{
log
.
Fatalln
(
err
)
}
// Response is a message ID string.
fmt
.
Println
(
"Successfully sent message:"
,
response
)
C#
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var
condition
=
"'stock-GOOG' in topics || 'industry-tech' in topics"
;
// See documentation on defining a message payload.
var
message
=
new
Message
()
{
Notification
=
new
Notification
()
{
Title
=
"$GOOG up 1.43% on the day"
,
Body
=
"$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
,
},
Condition
=
condition
,
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string
response
=
await
FirebaseMessaging
.
DefaultInstance
.
SendAsync
(
message
);
// Response is a message ID string.
Console
.
WriteLine
(
"Successfully sent message: "
+
response
);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"condition": "'dogs' in topics || 'cats' in topics",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message",
}
}
}
cURL command:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"notification": {
"title": "FCM Message",
"body": "This is a Firebase Cloud Messaging Topic Message!",
},
"condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Send messages to device groups
Sending messages to a device group is very similar to sending
messages to an individual device, using the same method to authorize send requests
. Set the token
field to the group notification key:
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
}
}
}
cURL command
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
},
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Send direct boot-enabled messages (Android only)
You can send messages to devices in direct boot mode using the HTTP v1 or legacy HTTP APIs. Before sending to devices in direct boot mode, make sure you have completed the steps to enable client devices to receive FCM messages in direct boot mode .
Send using the FCM v1 HTTP API
The message request must include the key "direct_boot_ok" : true
in the AndroidConfig
options of the request body. For example:
https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
"data": {
"score": "5x1",
"time": "15:10"
},
"android": {
"direct_boot_ok": true,
},
}
Customize messages across platforms
The Firebase
Admin SDK
and the FCM v1 HTTP protocol both allow your message
requests to set all fields available in the message
object. This includes:
- a common set of fields to be interpreted by allapp instances that receive the message.
- platform-specific sets of fields, such as
AndroidConfigandWebpushConfig, interpreted only by app instances running on the specified platform.
Platform-specific blocks give you flexibility to customize messages for different platforms to ensure that they are handled correctly when received. The FCM backend will take all specified parameters into account and customize the message for each platform.
When to use common fields
Use common fields when you're:
- Targeting app instances on allplatforms — Apple, Android, and web
- Sending messages to topics
All app instances, regardless of platform, can interpret the following common fields:
When to use platform-specific fields
Use platform-specific fields when you want to:
- Send fields only to particular platforms
- Send platform-specific fields in addition to the common fields
Whenever you want to send values only to particular platforms, don'tuse common fields; use platform-specific fields. For example, to send a notification only to Apple platforms and web but not to Android, you must use two separate sets of fields, one for Apple and one for web.
When you are sending messages with specific delivery options , use platform-specific fields to set them. You can specify different values per platform if you want. However, even when you want to set essentially the same value across platforms, you must use platform-specific fields. This is because each platform may interpret the value slightly differently—for example, time-to-live is set on Android as an expiration time in seconds, while on Apple it is set as an expiration date .
Example: notification message with color and icon options
This example send request sends a common notification title and content to all platforms, but it also sends some platform-specific overrides to Android devices.
For Android, the request sets a special icon and color to display on Android devices. As noted in the reference for AndroidNotification , the color is specified in #rrggbb format, and the image must be a drawable icon resource local to the Android app.
Here's an approximation of the visual effect on a user's device:
Node.js
const
topicName
=
'industry-tech'
;
const
message
=
{
notification
:
{
title
:
'`$FooCorp` up 1.43% on the day'
,
body
:
'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
android
:
{
notification
:
{
icon
:
'stock_ticker_update'
,
color
:
'#7e55c3'
}
},
topic
:
topicName
,
};
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
Java
Message
message
=
Message
.
builder
()
.
setNotification
(
Notification
.
builder
()
.
setTitle
(
"$GOOG up 1.43% on the day"
)
.
setBody
(
"$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
)
.
build
())
.
setAndroidConfig
(
AndroidConfig
.
builder
()
.
setTtl
(
3600
*
1000
)
.
setNotification
(
AndroidNotification
.
builder
()
.
setIcon
(
"stock_ticker_update"
)
.
setColor
(
"#f45342"
)
.
build
())
.
build
())
.
setApnsConfig
(
ApnsConfig
.
builder
()
.
setAps
(
Aps
.
builder
()
.
setBadge
(
42
)
.
build
())
.
build
())
.
setTopic
(
"industry-tech"
)
.
build
();
Python
message
=
messaging
.
Message
(
notification
=
messaging
.
Notification
(
title
=
'$GOOG up 1.43
% o
n the day'
,
body
=
'$GOOG gained 11.80 points to close at 835.67, up 1.43
% o
n the day.'
,
),
android
=
messaging
.
AndroidConfig
(
ttl
=
datetime
.
timedelta
(
seconds
=
3600
),
priority
=
'normal'
,
notification
=
messaging
.
AndroidNotification
(
icon
=
'stock_ticker_update'
,
color
=
'#f45342'
),
),
apns
=
messaging
.
APNSConfig
(
payload
=
messaging
.
APNSPayload
(
aps
=
messaging
.
Aps
(
badge
=
42
),
),
),
topic
=
'industry-tech'
,
)
Go
oneHour
:=
time
.
Duration
(
1
)
*
time
.
Hour
badge
:=
42
message
:=
& messaging
.
Message
{
Notification
:
& messaging
.
Notification
{
Title
:
"$GOOG up 1.43% on the day"
,
Body
:
"$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
,
},
Android
:
& messaging
.
AndroidConfig
{
TTL
:
& oneHour
,
Notification
:
& messaging
.
AndroidNotification
{
Icon
:
"stock_ticker_update"
,
Color
:
"#f45342"
,
},
},
APNS
:
& messaging
.
APNSConfig
{
Payload
:
& messaging
.
APNSPayload
{
Aps
:
& messaging
.
Aps
{
Badge
:
& badge
,
},
},
},
Topic
:
"industry-tech"
,
}
C#
var
message
=
new
Message
{
Notification
=
new
Notification
()
{
Title
=
"$GOOG up 1.43% on the day"
,
Body
=
"$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."
,
},
Android
=
new
AndroidConfig
()
{
TimeToLive
=
TimeSpan
.
FromHours
(
1
),
Notification
=
new
AndroidNotification
()
{
Icon
=
"stock_ticker_update"
,
Color
=
"#f45342"
,
},
},
Apns
=
new
ApnsConfig
()
{
Aps
=
new
Aps
()
{
Badge
=
42
,
},
},
Topic
=
"industry-tech"
,
};
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":" `$FooCorp`
up 1.43% on the day",
"body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
},
"android":{
"notification":{
"icon":"stock_ticker_update",
"color":"#7e55c3"
}
}
}
}
See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.
Example: notification message with a custom image
The following example send request sends a common notification title to all platforms, but it also sends an image. Here's an approximation of the visual effect on a user's device:
Node.js
const
topicName
=
'industry-tech'
;
const
message
=
{
notification
:
{
title
:
'Sparky says hello!'
},
android
:
{
notification
:
{
imageUrl
:
'https://foo.bar.pizza-monster.png'
}
},
apns
:
{
payload
:
{
aps
:
{
'mutable-content'
:
1
}
},
fcm_options
:
{
image
:
'https://foo.bar.pizza-monster.png'
}
},
webpush
:
{
headers
:
{
image
:
'https://foo.bar.pizza-monster.png'
}
},
topic
:
topicName
,
};
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"Sparky says hello!",
},
"android":{
"notification":{
"image":"https://foo.bar/pizza-monster.png"
}
},
"apns":{
"payload":{
"aps":{
"mutable-content":1
}
},
"fcm_options": {
"image":"https://foo.bar/pizza-monster.png"
}
},
"webpush":{
"headers":{
"image":"https://foo.bar/pizza-monster.png"
}
}
}
}
See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.
Example: notification message with an associated click action
The following example send request sends a common notification title to all platforms, but it also sends an action for the app to perform in response to user interacting with the notification. Here's an approximation of the visual effect on a user's device:
Node.js
const
topicName
=
'industry-tech'
;
const
message
=
{
notification
:
{
title
:
'Breaking News....'
},
android
:
{
notification
:
{
clickAction
:
'news_intent'
}
},
apns
:
{
payload
:
{
aps
:
{
'category'
:
'INVITE_CATEGORY'
}
}
},
webpush
:
{
fcmOptions
:
{
link
:
'breakingnews.html'
}
},
topic
:
topicName
,
};
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"Breaking News...",
},
"android":{
"notification":{
"click_action":"news_intent"
}
},
"apns":{
"payload":{
"aps":{
"category" : "INVITE_CATEGORY"
}
},
},
"webpush":{
"fcm_options":{
"link":"breakingnews.html"
}
}
}
}
See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.
Example: notification message with localization options
The following example send request sends localization options for the client to display localized messages. Here's an approximation of the visual effect on a user's device:
Node.js
var
topicName
=
'industry-tech'
;
var
message
=
{
android
:
{
ttl
:
3600000
,
notification
:
{
bodyLocKey
:
'STOCK_NOTIFICATION_BODY'
,
bodyLocArgs
:
[
'FooCorp'
,
'11.80'
,
'835.67'
,
'1.43'
]
}
},
apns
:
{
payload
:
{
aps
:
{
alert
:
{
locKey
:
'STOCK_NOTIFICATION_BODY'
,
locArgs
:
[
'FooCorp'
,
'11.80'
,
'835.67'
,
'1.43'
]
}
}
}
},
topic
:
topicName
,
};
getMessaging
().
send
(
message
)
.
then
((
response
)
=
>
{
// Response is a message ID string.
console
.
log
(
'Successfully sent message:'
,
response
);
})
.
catch
((
error
)
=
>
{
console
.
log
(
'Error sending message:'
,
error
);
});
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"Tech",
"android":{
"ttl":"3600s",
"notification":{
"body_loc_key": "STOCK_NOTIFICATION_BODY",
"body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
"apns":{
"payload":{
"aps":{
"alert" : {
"loc-key": "STOCK_NOTIFICATION_BODY",
"loc-args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
},
},
},
}'
See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.
