REST Resource: projects.messages

Resource: Message

Message to send by Firebase Cloud Messaging Service.

JSON representation 
{
  "name": string,
  "data": {
    string: string,
    ...
  },
  "notification": {
    object (Notification)
  },
  "android": {
    object (AndroidConfig)
  },
  "webpush": {
    object (WebpushConfig)
  },
  "apns": {
    object (ApnsConfig)
  },
  "fcm_options": {
    object (FcmOptions)
  },

  // Union field target can be only one of the following:
  "token": string,
  "topic": string,
  "condition": string
  // End of list of possible types for union field target.
}
Fields
name

string

Output Only. The identifier of the message sent, in the format of projects/*/messages/{message_id}.
data

map (key: string, value: string)

Input only. Arbitrary key/value payload, which must be UTF-8 encoded. The key should not be a reserved word ("from", "message_type", or any word starting with "google." or "gcm.notification."). When sending payloads containing only data fields to iOS devices, only normal priority ("apns-priority": "5") is allowed in ApnsConfig.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
notification

object (Notification)

Input only. Basic notification template to use across all platforms.
android

object (AndroidConfig)

Input only. Android specific options for messages sent through FCM connection server.
webpush

object (WebpushConfig)

Input only. Webpush protocol options.
apns

object (ApnsConfig)

Input only. Apple Push Notification Service specific options.
fcm_options

object (FcmOptions)

Input only. Template for FCM SDK feature options to use across all platforms.
Union field target. Required. Input only. Target to send a message to. target can be only one of the following:
token

string

Registration token to send a message to.
topic

string

Topic name to send a message to, e.g. "weather". Note: "/topics/" prefix should not be provided.
condition

string

Condition to send a message to, e.g. "'foo' in topics && 'bar' in topics".

Notification

Basic notification template to use across all platforms.

JSON representation 
{
  "title": string,
  "body": string,
  "image": string
}
Fields
title

string

The notification's title.
body

string

The notification's body text.
image

string

Contains the URL of an image that is going to be downloaded on the device and displayed in a notification. JPEG, PNG, BMP have full support across platforms. Animated GIF and video only work on iOS. WebP and HEIF have varying levels of support across platforms and platform versions. Android has 1MB image size limit. Quota usage and implications/costs for hosting image on Firebase Storage: https://firebase.google.com/pricing

AndroidConfig

Android specific options for messages sent through FCM connection server.

JSON representation 
{
  "collapse_key": string,
  "priority": enum (AndroidMessagePriority),
  "ttl": string,
  "restricted_package_name": string,
  "data": {
    string: string,
    ...
  },
  "notification": {
    object (AndroidNotification)
  },
  "fcm_options": {
    object (AndroidFcmOptions)
  },
  "direct_boot_ok": boolean
}
Fields
collapse_key

string

An identifier of a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed. A maximum of 4 different collapse keys is allowed at any given time.
priority

enum (AndroidMessagePriority)

Message priority. Can take "normal" and "high" values. For more information, see Setting the priority of a message.
ttl

string (Duration format)

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 if not set. Set it to 0 if want to send the message immediately. In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s". The ttl will be rounded down to the nearest second.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
restricted_package_name

string

Package name of the application where the registration token must match in order to receive the message.
data

map (key: string, value: string)

Arbitrary key/value payload. If present, it will override google.firebase.fcm.v1.Message.data.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
notification

object (AndroidNotification)

Notification to send to android devices.
fcm_options

object (AndroidFcmOptions)

Options for features provided by the FCM SDK for Android.
direct_boot_ok

boolean

If set to true, messages will be allowed to be delivered to the app while the device is in direct boot mode. See Support Direct Boot mode.

AndroidMessagePriority

Priority of a message to send to Android devices. Note this priority is an FCM concept that controls when the message is delivered. See FCM guides. Additionally, you can determine notification display priority on targeted Android devices using AndroidNotification.NotificationPriority.

Enums
NORMAL Default priority for data messages. Normal priority messages won't open network connections on a sleeping device, and their delivery may be delayed to conserve the battery. For less time-sensitive messages, such as notifications of new email or other data to sync, choose normal delivery priority.
HIGH Default priority for notification messages. FCM attempts to deliver high priority messages immediately, allowing the FCM service to wake a sleeping device when possible and open a network connection to your app server. Apps with instant messaging, chat, or voice call alerts, for example, generally need to open a network connection and make sure FCM delivers the message to the device without delay. Set high priority if the message is time-critical and requires the user's immediate interaction, but beware that setting your messages to high priority contributes more to battery drain compared with normal priority messages.

AndroidNotification

Notification to send to android devices.

JSON representation 
{
  "title": string,
  "body": string,
  "icon": string,
  "color": string,
  "sound": string,
  "tag": string,
  "click_action": string,
  "body_loc_key": string,
  "body_loc_args": [
    string
  ],
  "title_loc_key": string,
  "title_loc_args": [
    string
  ],
  "channel_id": string,
  "ticker": string,
  "sticky": boolean,
  "event_time": string,
  "local_only": boolean,
  "notification_priority": enum (NotificationPriority),
  "default_sound": boolean,
  "default_vibrate_timings": boolean,
  "default_light_settings": boolean,
  "vibrate_timings": [
    string
  ],
  "visibility": enum (Visibility),
  "notification_count": integer,
  "light_settings": {
    object (LightSettings)
  },
  "image": string,
  "bypass_proxy_notification": boolean,
  "proxy": enum (Proxy)
}
Fields
title

string

The notification's title. If present, it will override google.firebase.fcm.v1.Notification.title.
body

string

The notification's body text. If present, it will override google.firebase.fcm.v1.Notification.body.
icon

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

string

The notification's icon color, expressed in #rrggbb format.
sound

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

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

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

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[]

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

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[]

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

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

string

Sets the "ticker" text, which is sent to accessibility services. Prior to API level 21 (Lollipop), sets the text that is displayed in the status bar when the notification first arrives.
sticky

boolean

When set to false or unset, the notification is automatically dismissed when the user clicks it in the panel. When set to true, the notification persists even when the user clicks it.
event_time

string (Timestamp format)

Set the time that the event in the notification occurred. Notifications in the panel are sorted by this time. A point in time is represented using protobuf.Timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
local_only

boolean

Set whether or not this notification is relevant only to the current device. Some notifications can be bridged to other devices for remote display, such as a Wear OS watch. This hint can be set to recommend this notification not be bridged. See Wear OS guides
notification_priority

enum (NotificationPriority)

Set the relative priority for this notification. Priority is an indication of how much of the user's attention should be consumed by this notification. Low-priority notifications may be hidden from the user in certain situations, while the user might be interrupted for a higher-priority notification. The effect of setting the same priorities may differ slightly on different platforms. Note this priority differs from AndroidMessagePriority. This priority is processed by the client after the message has been delivered, whereas AndroidMessagePriority is an FCM concept that controls when the message is delivered.
default_sound

boolean

If set to true, use the Android framework's default sound for the notification. Default values are specified in config.xml.
default_vibrate_timings

boolean

If set to true, use the Android framework's default vibrate pattern for the notification. Default values are specified in config.xml. If default_vibrate_timings is set to true and vibrate_timings is also set, the default value is used instead of the user-specified vibrate_timings.
default_light_settings

boolean

If set to true, use the Android framework's default LED light settings for the notification. Default values are specified in config.xml. If default_light_settings is set to true and light_settings is also set, the user-specified light_settings is used instead of the default value.
vibrate_timings[]

string (Duration format)

Set the vibration pattern to use. Pass in an array of protobuf.Duration to turn on or off the vibrator. The first value indicates the Duration to wait before turning the vibrator on. The next value indicates the Duration to keep the vibrator on. Subsequent values alternate between Duration to turn the vibrator off and to turn the vibrator on. If vibrate_timings is set and default_vibrate_timings is set to true, the default value is used instead of the user-specified vibrate_timings.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
visibility

enum (Visibility)

Set the Notification.visibility of the notification.
notification_count

integer

Sets the number of items this notification represents. May be displayed as a badge count for launchers that support badging.See Notification Badge. For example, this might be useful if you're using just one notification to represent multiple new messages but you want the count here to represent the number of total new messages. If zero or unspecified, systems that support badging use the default, which is to increment a number displayed on the long-press menu each time a new notification arrives.
light_settings

object (LightSettings)

Settings to control the notification's LED blinking rate and color if LED is available on the device. The total blinking time is controlled by the OS.
image

string

Contains the URL of an image that is going to be displayed in a notification. If present, it will override google.firebase.fcm.v1.Notification.image.
bypass_proxy_notification
(deprecated)

boolean

If set, display notifications delivered to the device will be handled by the app instead of the proxy.
proxy

enum (Proxy)

Setting to control when a notification may be proxied.

NotificationPriority

Priority levels of a notification.

Enums
PRIORITY_UNSPECIFIED If priority is unspecified, notification priority is set to PRIORITY_DEFAULT.
PRIORITY_MIN Lowest notification priority. Notifications with this PRIORITY_MIN might not be shown to the user except under special circumstances, such as detailed notification logs.
PRIORITY_LOW Lower notification priority. The UI may choose to show the notifications smaller, or at a different position in the list, compared with notifications with PRIORITY_DEFAULT.
PRIORITY_DEFAULT Default notification priority. If the application does not prioritize its own notifications, use this value for all notifications.
PRIORITY_HIGH Higher notification priority. Use this for more important notifications or alerts. The UI may choose to show these notifications larger, or at a different position in the notification lists, compared with notifications with PRIORITY_DEFAULT.
PRIORITY_MAX Highest notification priority. Use this for the application's most important items that require the user's prompt attention or input.

Visibility

Different visibility levels of a notification.

Enums
VISIBILITY_UNSPECIFIED If unspecified, default to Visibility.PRIVATE.
PRIVATE Show this notification on all lockscreens, but conceal sensitive or private information on secure lockscreens.
PUBLIC Show this notification in its entirety on all lockscreens.
SECRET Do not reveal any part of this notification on a secure lockscreen.

LightSettings

Settings to control notification LED.

JSON representation 
{
  "color": {
    object (Color)
  },
  "light_on_duration": string,
  "light_off_duration": string
}
Fields
color

object (Color)

Required. Set color of the LED with google.type.Color.
light_on_duration

string (Duration format)

Required. Along with light_off_duration, define the blink rate of LED flashes. Resolution defined by proto.Duration

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
light_off_duration

string (Duration format)

Required. Along with light_on_duration, define the blink rate of LED flashes. Resolution defined by proto.Duration

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

Color

Represents a color in the RGBA color space. This representation is designed for simplicity of conversion to and from color representations in various languages over compactness. For example, the fields of this representation can be trivially provided to the constructor of java.awt.Color in Java; it can also be trivially provided to UIColor's +colorWithRed:green:blue:alpha method in iOS; and, with just a little work, it can be easily formatted into a CSS rgba() string in JavaScript.

This reference page doesn't have information about the absolute color space that should be used to interpret the RGB value—for example, sRGB, Adobe RGB, DCI-P3, and BT.2020. By default, applications should assume the sRGB color space.

When color equality needs to be decided, implementations, unless documented otherwise, treat two colors as equal if all their red, green, blue, and alpha values each differ by at most 1e-5.

Example (Java):

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

Example (iOS / Obj-C):

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

Example (JavaScript):

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...
JSON representation 
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
Fields
red

number

The amount of red in the color as a value in the interval [0, 1].
green

number

The amount of green in the color as a value in the interval [0, 1].
blue

number

The amount of blue in the color as a value in the interval [0, 1].
alpha

number

The fraction of this color that should be applied to the pixel. That is, the final pixel color is defined by the equation:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

This means that a value of 1.0 corresponds to a solid color, whereas a value of 0.0 corresponds to a completely transparent color. This uses a wrapper message rather than a simple float scalar so that it is possible to distinguish between a default value and the value being unset. If omitted, this color object is rendered as a solid color (as if the alpha value had been explicitly given a value of 1.0).

Proxy

Setting to control when a notification may be proxied.

Enums
PROXY_UNSPECIFIED If unspecified, default to Proxy.IF_PRIORITY_LOWERED.
ALLOW Try to proxy this notification.
DENY Do not proxy this notification.
IF_PRIORITY_LOWERED Only try to proxy this notification if its AndroidMessagePriority was lowered from HIGH to NORMAL on the device.

AndroidFcmOptions

Options for features provided by the FCM SDK for Android.

JSON representation 
{
  "analytics_label": string
}
Fields
analytics_label

string

Label associated with the message's analytics data.

WebpushConfig

Webpush protocol options.

JSON representation 
{
  "headers": {
    string: string,
    ...
  },
  "data": {
    string: string,
    ...
  },
  "notification": {
    object
  },
  "fcm_options": {
    object (WebpushFcmOptions)
  }
}
Fields
headers

map (key: string, value: string)

HTTP headers defined in webpush protocol. Refer to Webpush protocol for supported headers, e.g. "TTL": "15".

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
data

map (key: string, value: string)

Arbitrary key/value payload. If present, it will override google.firebase.fcm.v1.Message.data.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
notification

object (Struct format)

Web Notification options as a JSON object. Supports Notification instance properties as defined in Web Notification API. If present, "title" and "body" fields override google.firebase.fcm.v1.Notification.title and google.firebase.fcm.v1.Notification.body.
fcm_options

object (WebpushFcmOptions)

Options for features provided by the FCM SDK for Web.

WebpushFcmOptions

Options for features provided by the FCM SDK for Web.

JSON representation 
{
  "link": string,
  "analytics_label": string
}
Fields
analytics_label

string

Label associated with the message's analytics data.

ApnsConfig

Apple Push Notification Service specific options.

JSON representation 
{
  "headers": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "fcm_options": {
    object (ApnsFcmOptions)
  },
  "live_activity_token": string
}
Fields
headers

map (key: string, value: string)

HTTP request headers defined in Apple Push Notification Service. Refer to APNs request headers for supported headers such as apns-expiration and apns-priority.

The backend sets a default value for apns-expiration of 30 days and a default value for apns-priority of 10 if not explicitly set.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

APNs payload as a JSON object, including both aps dictionary and custom payload. See Payload Key Reference. If present, it overrides google.firebase.fcm.v1.Notification.title and google.firebase.fcm.v1.Notification.body.
fcm_options

object (ApnsFcmOptions)

Options for features provided by the FCM SDK for iOS.
live_activity_token

string

Optional. Apple Live Activity token to send updates to. This token can either be a push token or push-to-start token from Apple.

To start, update, or end a live activity remotely using FCM, construct an aps payload and put it in the apns.payload field.

ApnsFcmOptions

Options for features provided by the FCM SDK for iOS.

JSON representation 
{
  "analytics_label": string,
  "image": string
}
Fields
analytics_label

string

Label associated with the message's analytics data.
image

string

Contains the URL of an image that is going to be displayed in a notification. If present, it will override google.firebase.fcm.v1.Notification.image.

FcmOptions

Platform independent options for features provided by the FCM SDKs.

JSON representation 
{
  "analytics_label": string
}
Fields
analytics_label

string

Label associated with the message's analytics data.

Methods

send

 Send a message to specified target (a registration token, topic or condition).