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.
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 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 |
|
mutable_content |
Optional, JSON boolean | On Apple platforms, 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 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 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 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.
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
|
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 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
Corresponds to See Payload Key Reference and Localizing the Content of Your Remote Notifications for more information. |
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 |
sound |
Optional, string |
The sound to play when the device receives the notification.
Supports |
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 |
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
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
See Formatting and Styling for more information. |
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.
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, 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 |
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.
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).
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).
|
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. |
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. |
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.
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:
|
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:
|
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:
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.
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. |