Firebase Cloud Messaging HTTP protocol

This document provides a reference for the HTTP syntax used to pass messages from your app server to client apps via Firebase Cloud Messaging. 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
Downstream message error response codes

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 `/topics/`). To send to multiple topics, use the `condition` parameter.
`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 `to` parameter. 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: `&&`, `\|\|`. Maximum two operators per topic message supported.
`notification_key` Deprecated	Optional, string	This parameter is deprecated. Instead, use `to` to specify message recipients. For more information on how to send messages to multiple devices, see the documentation for your platform.
Options
`collapse_key`	Optional, string	This parameter identifies a group of messages (e.g., with `collapse_key: "Updates Available"`) that can be collapsed, so that only the last message gets sent when delivery can be resumed. This is intended to avoid sending too many of the same messages when the device comes back online or becomes active. 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 `content-available` in the APNs payload. When a notification or message is sent and this is set to `true`, an inactive client app is awoken, and the message is sent through APNs as a silent notification and not through the FCM connection server. Note that silent notifications in APNs are not guaranteed to be delivered, and can depend on factors such as the user turning on Low Power Mode, force quitting the app, etc. On Android, data messages wake the app by default. On Chrome, currently not supported.
`mutable_content`	Optional, JSON boolean	Currently for iOS 10+ devices only. On iOS, use this field to represent `mutable-content` in the APNs payload. When a notification is sent and this is set to `true`, the content of the notification can be modified before it is displayed, using a Notification Service app extension. This parameter will be ignored for Android and web.
`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_ name` (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 `true`, allows developers to test a request without actually sending a message. The default value is `false`.
Payload
`data`	Optional, object	This parameter specifies the custom key-value pairs of the message's payload. For example, with `data:{"score":"3x1"}:` 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 `AppDelegate application:didReceiveRemoteNotification:`. On Android, this would result in an intent extra named `score` with the string value `3x1`. The key should not be a reserved word ("from" or any word starting with "google" or "gcm"). Do not use any of the words defined in this table (such as `collapse_key`). 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 `Library/Sounds` folder of the app's data container. See the iOS Developer Library for more information. For critical notifications use a dictionary that contains sound information for critical alerts. See the iOS Developer Library for keys required. For regular notifications, use the sound string instead.
`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 `0`, the badge is removed.
`click_action`	Optional, string	The action associated with a user click on the notification. Corresponds to `category` in the APNs payload.
`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 `loc-key` in the APNs payload. 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 `body_loc_key` to use to localize the body text to the user's current localization. Corresponds to `loc-args` in the APNs payload. 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 `title-loc-key` in the APNs payload. See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.
`title_loc_args`	Optional, JSON array as string	Variable string values to be used in place of the format specifiers in `title_loc_key` to use to localize the title text to the user's current localization. Corresponds to `title-loc-args` in the APNs payload. See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information.

Table 2b. Android — keys for notification messages

Parameter	Usage	Description
`title`	Optional, string	The notification's title.
`body`	Optional, string	The notification's body text.
`android_channel_id`	Optional, string	The notification's channel id (new in Android O). The app must create a channel with this channel ID before any notification with this channel ID is received. If you don't send this channel ID in the request, or if the channel ID provided has not yet been created by the app, FCM uses the channel ID specified in the app manifest.
`icon`	Optional, string	The notification's icon. Sets the notification icon to `myicon` for drawable resource `myicon`. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest.
`sound`	Optional, string	The sound to play when the device receives the notification. Supports `"default"` or the filename of a sound resource bundled in the app. Sound files must reside in `/res/raw/`.
`tag`	Optional, string	Identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification. If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.
`color`	Optional, string	The notification's icon color, expressed in `#rrggbb` format.
`click_action`	Optional, string	The action associated with a user click on the notification. If specified, an activity with a matching intent filter is launched when a user clicks on the notification.
`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. See String Resources for more information.
`body_loc_args`	Optional, JSON array as string	Variable string values to be used in place of the format specifiers in `body_loc_key` to use to localize the body text to the user's current localization. See Formatting and Styling 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. See String Resources for more information.
`title_loc_args`	Optional, JSON array as string	Variable string values to be used in place of the format specifiers in `title_loc_key` to use to localize the title text to the user's current localization. See Formatting and Styling for more information.

Table 2c. Web (JavaScript) — keys for notification messages

Parameter	Usage	Description
`title`	Optional, string	The notification's title.
`body`	Optional, string	The notification's body text.
`icon`	Optional, string	The URL to use for the notification's icon.
`click_action`	Optional, string	The action associated with a user click on the notification. For all URL values, HTTPS is required.

Downstream HTTP messages (Plain Text)

The following table lists the syntax for targets, options, and payload in plain text downstream HTTP messages.

Table 3. Targets, options, and payload for downstream plain text HTTP messages.

Parameter	Usage	Description
Targets
`registration_id`	Required, string	This parameter specifies the client apps (registration IDs) receiving the message. Multicast messaging (sending to more than one registration ID) is allowed using HTTP JSON format only.
Options
`collapse_key`	Optional, string	See table 1 for details.
`time_to_live`	Optional, number	See table 1 for details.
`restricted_package_name`	Optional, string	See table 1 for details.
`dry_run`	Optional, boolean	See table 1 for details.
Payload
`data.<key>`	Optional, string	This parameter specifies the key-value pairs of the m