This document provides a reference for the HTTP syntax used to pass messages from your app server to client apps via Firebase Cloud Messaging.
When using the legacy HTTP protocol, your app server must direct all HTTP requests to this endpoint:https://fcm.googleapis.com/fcm/send
The available parameters and options fall into the following broad categories:
Downstream message syntax
This section gives the syntax for sending downstream messages and interpreting HTTP responses from Firebase Cloud Messaging.
Downstream HTTP messages (JSON)
The following table lists the targets, options, and payload for HTTP JSON messages.
Table 1. Targets, options, and payload for downstream HTTP messages (JSON).
Parameter | Usage | Description | |
---|---|---|---|
Targets | |||
to |
Optional, string |
This parameter specifies the recipient of a message.
The value can be a device's registration token, a device group's
notification key, or a single topic (prefixed with
|
|
registration_ids | Optional, array of strings |
This parameter specifies the recipient of a multicast message, a message sent to more than one registration token.
The value should be an array of registration tokens to which to send the
multicast message. The array must contain at least 1 and at most 1000
registration tokens. To send a message to a single device, use the
Multicast messages are only allowed using the HTTP JSON format. |
|
condition |
Optional, string | This parameter specifies a logical expression of conditions that determine the message target. Supported condition: Topic, formatted as "'yourTopic' in topics". This value is case-insensitive. Supported operators: |
|
notification_key Deprecated |
Optional, string | This parameter is deprecated. Instead, use |
|
Options | |||
collapse_key |
Optional, string | This parameter identifies a group of messages (e.g., with
Note that there is no guarantee of the order in which messages get sent. Note: A maximum of 4 different collapse keys is allowed at any given time. This means a FCM connection server can simultaneously store 4 different messages per client app. If you exceed this number, there is no guarantee which 4 collapse keys the FCM connection server will keep. |
|
priority |
Optional, string | Sets the priority of the message. Valid values are "normal" and "high." On iOS, these correspond to APNs priorities 5 and 10. By default, notification messages are sent with high priority, and data messages are sent with normal priority. Normal priority optimizes the client app's battery consumption and should be used unless immediate delivery is required. For messages with normal priority, the app may receive the message with unspecified delay. When a message is sent with high priority, it is sent immediately, and the app can display a notification. |
|
content_available |
Optional, boolean | On iOS, use this field to represent |
|
mutable_content |
Optional, JSON boolean | Currently for iOS 10+ devices only. On iOS, use this field to represent
|
|
time_to_live |
Optional, number | This parameter specifies how long (in seconds) the message should be kept in FCM storage if the device is offline. The maximum time to live supported is 4 weeks, and the default value is 4 weeks. For more information, see Setting the lifespan of a message. |
|
restricted_package_
(Android only) |
Optional, string | This parameter specifies the package name of the application where the registration tokens must match in order to receive the message. | |
dry_run |
Optional, boolean | This parameter, when set to The default value is |
|
Payload | |||
data |
Optional, object | This parameter specifies the custom key-value pairs of the message's payload. For example, with On iOS, if the message is sent via APNs, it represents the custom data fields. If it is sent via FCM connection server,
it would be represented as key value dictionary in On Android, this would result in an intent extra named The key should not be a reserved word ("from", "message_type", or any word starting with
"google" or "gcm"). Do not use any of the words defined in this table
(such as Values in string types are recommended. You have to convert values in objects or other non-string data types (e.g., integers or booleans) to string. |
|
notification |
Optional, object | This parameter specifies the predefined, user-visible key-value pairs of
the notification payload. See Notification payload support for detail.
For more information about notification message and data message options,
see
Message types. If a notification payload is provided, or the
content_available option is set to true for a message to an iOS
device, the message is sent through APNs, otherwise it is sent through the
FCM connection server.
|
Notification payload support
The following tables list the predefined keys available for building notification messages for iOS and Android.
Table 2a. iOS — keys for notification messages
Parameter | Usage | Description |
---|---|---|
title |
Optional, string |
The notification's title. This field is not visible on iOS phones and tablets. |
body |
Optional, string |
The notification's body text. |
sound |
Optional, string or Dictionary |
The sound to play when the device receives the notification.
String specifying sound files in the main bundle of the client app or in the
|
badge |
Optional, string |
The value of the badge on the home screen app icon. If not specified, the badge is not changed.
If set to |
click_action |
Optional, string |
The action associated with a user click on the notification.
Corresponds to |
subtitle |
Optional, string |
The notification's subtitle. |
body_loc_key |
Optional, string |
The key to the body string in the app's string resources to use to localize the body text to the user's current localization.
Corresponds to See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information. |
body_loc_args |
Optional, JSON array as string |
Variable string values to be used in place of the format specifiers in
Corresponds to See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information. |
title_loc_key |
Optional, string |
The key to the title string in the app's string resources to use to localize the title text to the user's current localization.
Corresponds to See Payload Key Reference and |