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.

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 /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 that FCM can simultaneously store 4 different messages per client app. If you exceed this number, there is no guarantee which 4 collapse keys FCM will keep.

priority Optional, string

Sets the priority of the message. Valid values are "normal" and "high." On Apple platforms, 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 Apple platforms, 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 FCM. 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

On Apple platforms, 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 Apple platforms, if the message is sent via APNs, it represents the custom data fields. If it is sent via FCM, 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", "message_type", 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 Apple device, the message is sent through APNs, otherwise it is sent through FCM.

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 phones and tablets.

body Optional, string

The notification's body text.

sound Optional, string

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.

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 tokenss) receiving the message.

Multicast messaging (sending to more than one registration token) 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 message's payload. There is no limit on the number of key-value parameters, but there is a total message size limit of 4096 bytes.

For instance, in Android, "data.score"."3x1" would result in an intent extra named score with the string value 3x1.

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 collapse_key).

Interpreting a downstream message response

The app server should evaluate both the message response header and the body to interpret the message response sent from FCM. The following table describes the possible responses.

Table 4. Downstream HTTP message response header.

Response Description
200 Message was processed successfully. The response body will contain more details about the message status, but its format will depend whether the request was JSON or plain text. See table 5 for more details.
400 Only applies for JSON requests. Indicates that the request could not be parsed as JSON, or it contained invalid fields (for instance, passing a string where a number was expected). The exact failure reason is described in the response and the problem should be addressed before the request can be retried.
401 There was an error authenticating the sender account.
5xx Errors in the 500-599 range (such as 500 or 503) indicate that there was an internal error in the FCM backend while trying to process the request, or that the server is temporarily unavailable (for example, because of timeouts). Sender must retry later, honoring any Retry-After header included in the response. Application servers must implement exponential back-off.

The following table lists the fields in a downstream message response body (JSON).

Table 5. Downstream HTTP message response body (JSON).

Parameter Usage Description
multicast_id Required, number Unique ID (number) identifying the multicast message.
success Required, number Number of messages that were processed without an error.
failure Required, number Number of messages that could not be processed.
results Required, array of objects Array of objects representing the status of the messages processed. The objects are listed in the same order as the request (i.e., for each registration ID in the request, its result is listed in the same index in the response).
  • message_id: String specifying a unique ID for each successfully processed message.
  • error: String specifying the error that occurred when processing the message for the recipient. The possible values can be found in table 9.

Table 6. Topic message HTTP response body (JSON).

Parameter Usage Description
message_id Optional, number The topic message ID when FCM has successfully received the request and will attempt to deliver to all subscribed devices.
error Optional, string Error that occurred when processing the message. The possible values can be found in table 9.

Table 7. Success response for downstream HTTP message response body (Plain Text).

Parameter Usage Description
id Required, string This parameter specifies the unique message ID FCM processed successfully.
registration_id Optional, string This parameter specifies the registration token for the client app that the message was processed and sent to.

Table 8. Error response for downstream HTTP message response body (Plain Text).

Parameter Usage Description
Error Required, string This parameter specifies the error value while processing the message for the recipient. See table 9 for details.

Downstream message error response codes

The following table lists the error response codes for downstream messages.

Table 9. Downstream message error response codes.

Error HTTP Code Recommended Action
Missing Registration Token 200 + error:MissingRegistration Check that the request contains a registration token (in the registration_id in a plain text message, or in the to or registration_ids field in JSON).
Invalid Registration Token 200 + error:InvalidRegistration Check the format of the registration token you pass to the server. Make sure it matches the registration token the client app receives from registering with Firebase Notifications. Do not truncate or add additional characters.
Unregistered Device 200 + error:NotRegistered An existing registration token may cease to be valid in a number of scenarios, including:
  • If the client app unregisters with FCM.
  • If the client app is automatically unregistered, which can happen if the user uninstalls the application. For example, on iOS, if the APNs Feedback Service reported the APNs token as invalid.
  • If the registration token expires (for example, Google might decide to refresh registration tokens, or the APNs token has expired for iOS devices).
  • If the client app is updated but the new version is not configured to receive messages.
For all these cases, remove this registration token from the app server and stop using it to send messages.
Invalid Package Name 200 + error:InvalidPackageName Make sure the message was addressed to a registration token whose package name matches the value passed in the request.
Authentication Error 401 The sender account used to send a message couldn't be authenticated. Possible causes are:
  • Authorization header missing or with invalid syntax in HTTP request.
  • The Firebase project that the specified server key belongs to is incorrect.
  • Legacy server keys only—the request originated from a server not whitelisted in the Server key IPs.
Check that the token you're sending inside the Authentication header is the correct server key associated with your project. See Checking the validity of a server key for details. If you are using a legacy server key, you're recommended to upgrade to a new key that has no IP restrictions. See Migrate legacy server keys.
Mismatched Sender 200 + error:MismatchSenderId A registration token is tied to a certain group of senders. When a client app registers for FCM, it must specify which senders are allowed to send messages. You should use one of those sender IDs when sending messages to the client app. If you switch to a different sender, the existing registration tokens won't work.
Invalid JSON 400 Check that the JSON message is properly formatted and contains valid fields (for instance, making sure the right data type is passed in).
Invalid Parameters 400 + error:InvalidParameters Check that the provided parameters have the right name and type.
Message Too Big 200 + error:MessageTooBig Check that the total size of the payload data included in a message does not exceed FCM limits: 4096 bytes for most messages, or 2048 bytes in the case of messages to topics. This includes both the keys and the values.
Invalid Data Key 200 + error:
InvalidDataKey
Check that the payload data does not contain a key (such as from, or gcm, or any value prefixed by google) that is used internally by FCM. Note that some words (such as collapse_key) are also used by FCM but are allowed in the payload, in which case the payload value will be overridden by the FCM value.
Invalid Time to Live 200 + error:InvalidTtl Check that the value used in time_to_live is an integer representing a duration in seconds between 0 and 2,419,200 (4 weeks).
Timeout 5xx or 200 + error:Unavailable

The server couldn't process the request in time. Retry the same request, but you must:

  • Honor the Retry-After header if it is included in the response from the FCM Connection Server.
  • Implement exponential back-off in your retry mechanism. (e.g. if you waited one second before the first retry, wait at least two second before the next one, then 4 seconds and so on). If you're sending multiple messages, delay each one independently by an additional random amount to avoid issuing a new request for all messages at the same time.

Senders that cause problems risk being blacklisted.

Internal Server Error 500 or 200 + error:InternalServerError The server encountered an error while trying to process the request. You could retry the same request following the requirements listed in "Timeout" (see row above). If the error persists, please contact Firebase support.
Device Message Rate Exceeded 200 + error:
DeviceMessageRate
Exceeded

The rate of messages to a particular device is too high. If an Apple app sends messages at a rate exceeding APNs limits, it may receive this error message

Reduce the number of messages sent to this device and use exponential backoff to retry sending.

Topics Message Rate Exceeded 200 + error:
TopicsMessageRate
Exceeded
The rate of messages to subscribers to a particular topic is too high. Reduce the number of messages sent for this topic and use exponential backoff to retry sending.
Invalid APNs credentials 200 + error:
InvalidApnsCredential
A message targeted to an Apple device could not be sent because the required APNs authentication key was not uploaded or has expired. Check the validity of your development and production credentials.

Device group management

The following table lists the keys for creating device groups and adding and removing members. For more information, see the guide for your platform, iOS+ or Android.

Table 10. Device group management keys.

Parameter Usage Description
operation Required, string The operation to run.Valid values are create, add, and remove.
notification_key_name Required, string The user-defined name of the device group to create or modify.
notification_key Required (except for create operation, string Unique identifier of the device group. This value is returned in the response for a successful create operation, and is required for all subsequent operations on the device group.
registration_ids Required, array of strings The device tokens to add or remove. If you remove all existing registration tokens from a device group, FCM deletes the device group.