FCM Payload Reference

Complete reference for all fields in an FCM HTTP v1 API message.

Message Structure

The FCM HTTP v1 API uses the following top-level structure:

json
{
  "message": {
    "token": "device-token",
    "notification": { ... },
    "data": { ... },
    "android": { ... },
    "apns": { ... },
    "webpush": { ... },
    "fcm_options": { ... }
  }
}

Target (Required — exactly one)

Field	Type	Description
`token`	string	A specific device registration token
`topic`	string	A topic name (without `/topics/` prefix)
`condition`	string	A condition expression, e.g. `'TopicA' in topics && 'TopicB' in topics`

Notification Object

Common fields displayed by the system notification tray:

Field	Type	Description
`title`	string	Notification title
`body`	string	Notification body text
`image`	string	URL of an image to display in the notification

Example:

json
{
  "title": "Order Update",
  "body": "Your order #1234 has been shipped!",
  "image": "https://example.com/shipping.png"
}

Data Object

Custom key-value pairs delivered to your app. All values must be strings.

json
{
  "orderId": "1234",
  "type": "shipping_update",
  "deepLink": "/orders/1234"
}

Note: Data messages are handled by your app code. They won't display a notification automatically unless your app creates one.

Android Overrides

Platform-specific configuration for Android devices:

json
{
  "android": {
    "collapse_key": "order_updates",
    "priority": "high",
    "ttl": "3600s",
    "notification": {
      "channel_id": "my_channel",
      "sound": "default",
      "click_action": "OPEN_ORDER",
      "color": "#7c3aed",
      "icon": "ic_notification",
      "tag": "order-1234"
    },
    "data": {
      "android_specific_key": "value"
    }
  }
}

Field	Description
`collapse_key`	Identifier for a group of messages that can be collapsed — only the last message is delivered when the device comes online. Max 4 different collapse keys at a time.
`priority`	`"high"` or `"normal"` (default). High priority wakes the device.
`ttl`	Time to live in seconds format, e.g. `"3600s"`. Default: 28 days.
`notification.channel_id`	Android notification channel ID (required for Android 8+)
`notification.sound`	`"default"` or a custom sound file name
`notification.click_action`	Activity intent action when notification is tapped
`notification.color`	Notification icon color in `#rrggbb` format
`notification.icon`	Notification icon resource name
`notification.tag`	Replace existing notification with same tag

APNs Overrides (iOS)

json
{
  "apns": {
    "headers": {
      "apns-priority": "10"
    },
    "payload": {
      "aps": {
        "badge": 1,
        "sound": "default",
        "category": "ORDER_UPDATE",
        "content-available": 1,
        "mutable-content": 1
      }
    }
  }
}

Field	Description
`headers.apns-priority`	`"10"` (immediate) or `"5"` (power-saving)
`payload.aps.badge`	Badge count on app icon
`payload.aps.sound`	`"default"` or custom sound file
`payload.aps.category`	Action category for interactive notifications
`payload.aps.content-available`	`1` for silent/background notification
`payload.aps.mutable-content`	`1` to allow notification service extension to modify

Web Push Overrides

json
{
  "webpush": {
    "headers": {
      "TTL": "3600",
      "Urgency": "high"
    },
    "notification": {
      "icon": "https://example.com/icon.png"
    },
    "fcm_options": {
      "link": "https://example.com/orders"
    }
  }
}

Field	Description
`headers.TTL`	Time to live in seconds for the push message
`headers.Urgency`	`"high"`, `"normal"`, `"low"`, or `"very-low"`
`notification`	Web Notification API properties — `icon`, `badge`, `image`, etc.
`fcm_options.link`	URL to open when the user clicks the notification (must be HTTPS)

FCM Options

json
{
  "fcm_options": {
    "analytics_label": "order_notification"
  }
}

Use analytics_label to filter notification analytics in Firebase Console.

Maximum Payload Size

The total message payload must not exceed 4096 bytes (4 KB). This includes notification, data, and all platform-specific fields combined.

Getting Started
Troubleshooting
Platform guides: Flutter · Android · iOS · Web · React Native