Accéder à la console

Firebase Cloud Messaging XMPP protocol

This document provides a reference for the XMPP syntax used to pass messages between your app server, client apps, and Firebase Cloud Messaging (FCM). Your app server must connect to these endpoints:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

The available parameters and options fall into these categories:

Downstream message syntax

This section gives the syntax for sending downstream messages.

Downstream XMPP messages (JSON)

The following table lists the targets, options, and payload for XMPP JSON messages.

Table 1 Targets, options, and payload for downstream XMPP messages (JSON).

Parameter Usage Description
Target
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.

condition Optional, string

This parameter specifies a logical expression of conditions that determines 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.

Options
message_id Required, string

This parameter uniquely identifies a message in an XMPP connection.

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 is resumed. This is intended to avoid sending too many of the same messages when the device comes back online or comes out of doze.

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

delivery_receipt_
requested
Optional, boolean

This parameter lets the app server request confirmation of message delivery.

When this parameter is set to true, FCM sends a delivery receipt when the device confirms that it received the message.

Note: this parameter is not supported for messages sent to iOS devices. The default value is false.

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 key-value pairs of the message's payload.

For example, with data:{"score":"3x1"}:

On iOS, if the message is delivered by APNs, it represents the custom data fields. If it is delivered by FCM, it is represented as a key value dictionary in AppDelegate application:didReceiveRemoteNotification:.

On Android, this results 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 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.

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.

Interpret a downstream XMPP message response

The following table lists the fields that appear in a downstream XMPP message response.

Table 3 Downstream message XMPP response body.

Parameter Usage Description