FCM Notification Configuration

Send customizable push notifications to Android and iOS devices using the FCM Notification Microservice. All platform-specific handling (FCM HTTP v1, APNs configuration) is managed automatically.

API Overview

The microservice accepts a SendPayload object with the following structure:

{
  // Required
  title: string;
  subtitle: string;  // Used as notification body

  // Targeting (one required)
  token?: string;           // Single device
  tokens?: string[];        // Multiple devices
  topic?: string;           // Topic subscription (default: "all")

  // Delivery priority
  priority?: "high" | "normal";  // Default: "normal"

  // Customization
  data?: {
    [key: string]: unknown;  // All custom fields go here
  }
}

Root-Level Fields

Field	Type	Required	Description	Default
`title`	string	✅	Notification title	-
`subtitle`	string	✅	Notification body text	-
`token`	string	❌	Single device token	-
`tokens`	string[]	❌	Multiple device tokens	-
`topic`	string	❌	Topic name	`"all"`
`priority`	`"high"` \\|`"normal"`	❌	FCM delivery priority	`"normal"`
`data`	object	❌	Custom notification fields	`{}`

Note: You must provide one of: token, tokens, or topic.

Data Fields (Customization)

All customization fields go inside the data object. The microservice automatically handles platform-specific formatting.

Cross-Platform Fields

Field	Type	Description	Android	iOS	Example
`image`	string	Image URL (HTTPS, .jpg/.png)	✅	✅	`"https://example.com/photo.jpg"`
`badge`	string	App icon badge count	✅	✅	`"5"`
`sound`	string	`"default"`, `"none"`, or common custom filename	✅	✅	`"order_updates.wav"`
`silent`	string	Silent notification	✅	✅	`"true"`
`category`	string	System category	✅	✅	`"message"`
`url`	string	Deep link URL on tap	✅	✅	`"https://app.com/orders/123"`

Android-Only Fields

Field	Type	Description	Example
`color`	string	Accent color (hex)	`"#FF5733"`
`icon`	string	Large icon URL	`"https://example.com/icon.png"`
`channel_id`	string	Notification channel (Android 8+)	`"order_updates"`
`vibrate`	string	Vibration pattern (ms, comma-separated)	`"0,250,250,250"`
`light_color`	string	LED color (hex)	`"#00FF00"`
`ticker`	string	Accessibility text	`"New order"`
`tag`	string	Replacement tag	`"order_123"`
`notification_id`	string	Numeric ID	`"12345"`
`sticky`	string	Ongoing notification	`"true"`
`auto_cancel`	string	Auto-dismiss on tap	`"true"`
`only_alert_once`	string	Alert once only	`"true"`
`big_text`	string	Expanded text	`"Long order details..."`
`summary_text`	string	Summary below content	`"2 new notifications"`
`sub_text`	string	Subtitle text	`"From John Doe"`
`group`	string	Group key	`"orders"`
`group_summary`	string	Is group summary	`"true"`
`group_alert_behavior`	string	`"all"`, `"summary"`, `"children"`	`"summary"`
`visibility`	string	`"public"`, `"private"`, `"secret"`	`"private"`
`when`	string	Timestamp (epoch ms)	`"1707350400000"`
`show_when`	string	Show timestamp	`"true"`
`use_chronometer`	string	Count-up timer	`"true"`
`chronometer_count_down`	string	Count-down timer	`"true"`
`progress`	string	Progress value	`"50"`
`progress_max`	string	Max progress	`"100"`
`progress_indeterminate`	string	Indeterminate progress	`"true"`

Custom Sound Rule

Use one shared sound filename in data.sound when you want one payload for Android and iOS.

Android: put file in android/app/src/main/res/raw/
iOS: bundle same filename in app target resources
Payload: use filename, for example "order_updates.wav"

Android strips extension for raw lookup, so order_updates.wav maps to raw resource order_updates.

iOS-Only Fields

Field	Type	Description	iOS Version	Example
`subtitle`	string	Secondary title line	10+	`"Vacation Photos"`
`thread_id`	string	Notification threading/grouping	10+	`"chat-123"`
`interruption_level`	string	`"passive"`, `"active"`, `"timeSensitive"`, `"critical"`	15+	`"timeSensitive"`
`relevance_score`	string	Ranking score (0.0-1.0)	15+	`"0.9"`
`critical_volume`	string	Critical alert volume (0.0-1.0)	12+	`"0.8"`
`target_content_id`	string	Notification replacement ID	15+	`"order_123"`
`filter_criteria`	string	Focus mode filtering	16+	`"urgent"`

Usage Examples

1. Basic Notification with Image

await FcmService.send({
  title: "New Order",
  subtitle: "Order #12345 received",
  priority: "high",
  token: "device_fcm_token_here",
  data: {
    image: "https://example.com/order.jpg",
    badge: "1",
    url: "https://app.com/orders/12345"
  }
}, "your-firebase-project-id");

2. iOS Time-Sensitive Notification

await FcmService.send({
  title: "Delivery Arriving",
  subtitle: "Your order will arrive in 5 minutes",
  priority: "high",
  token: "ios_device_token",
  data: {
    interruption_level: "timeSensitive",
    relevance_score: "0.9",
    badge: "1",
    sound: "default"
  }
}, "project-id");

3. Android Progress Notification

await FcmService.send({
  title: "Download Progress",
  subtitle: "Downloading file...",
  priority: "normal",
  token: "android_device_token",
  data: {
    progress: "45",
    progress_max: "100",
    progress_indeterminate: "false",
    sticky: "true",
    channel_id: "downloads"
  }
}, "project-id");

4. Silent Notification

await FcmService.send({
  title: "Background Sync",
  subtitle: "Data updated",
  priority: "normal",
  token: "device_token",
  data: {
    silent: "true",
    url: "https://app.com/sync"
  }
}, "project-id");

5. Grouped Notifications (Android)

// Send individual messages
await FcmService.send({
  title: "Message from Alice",
  subtitle: "Hey there!",
  priority: "high",
  token: "device_token",
  data: {
    group: "messages",
    tag: "msg_alice",
    group_alert_behavior: "children"
  }
}, "project-id");

await FcmService.send({
  title: "Message from Bob",
  subtitle: "What's up?",
  priority: "high",
  token: "device_token",
  data: {
    group: "messages",
    tag: "msg_bob",
    group_alert_behavior: "children"
  }
}, "project-id");

// Send group summary
await FcmService.send({
  title: "2 new messages",
  subtitle: "From Alice and Bob",
  priority: "high",
  token: "device_token",
  data: {
    group: "messages",
    group_summary: "true",
    group_alert_behavior: "summary",
    tag: "msg_summary"
  }
}, "project-id");

6. Critical Alert (iOS)

Requires Apple Critical Alerts entitlement

await FcmService.send({
  title: "🚨 Emergency Alert",
  subtitle: "Severe weather warning in your area",
  priority: "high",
  token: "ios_device_token",
  data: {
    interruption_level: "critical",
    critical_volume: "1.0",
    badge: "1"
  }
}, "project-id");

7. Multiple Devices (Batch Send)

await FcmService.send({
  title: "New Feature Available",
  subtitle: "Check out our latest update!",
  priority: "high",
  tokens: [
    "device_token_1",
    "device_token_2",
    "device_token_3"
  ],
  data: {
    image: "https://example.com/feature.jpg",
    url: "https://app.com/features/new"
  }
}, "project-id");

8. Topic Broadcast

await FcmService.send({
  title: "Breaking News",
  subtitle: "Important announcement for all users",
  priority: "high",
  topic: "all",  // or custom topic like "premium_users"
  data: {
    big_text: "We're excited to announce major updates coming next week!",
    url: "https://app.com/news"
  }
}, "project-id");

Priority Behavior

Priority	Android	iOS	Use Case
`"high"`	Immediate, wakes device	APNs priority 10	Time-sensitive, user-visible
`"normal"`	Batched, respects Doze	APNs priority 5	Background sync, non-urgent

Data Type Guidelines

Boolean Values

Send as strings: "true"/"false" or "1"/"0"

Numeric Values

Send as strings: "5", "0.9", "1707350400000"

URLs

Must be valid HTTPS URLs with proper file extensions for images (.jpg, .png, .gif)

Platform-Specific Notes

Android

Images downloaded asynchronously in FirebaseMessagingService
Channels control importance/sound (Android 8+)
DND can still suppress unless channel whitelisted

iOS

Images require Notification Service Extension with mutable-content: 1 (handled automatically)
timeSensitive bypasses most Focus modes
critical requires Apple entitlement (special approval)

Best Practices

Use priority: "high" only for user-visible, time-sensitive notifications
Always include url for deep linking on tap
Test on real devices - behavior varies by OS version
Keep images small (< 300 KB recommended)
Group related notifications with group (Android) or thread_id (iOS)
Provide big_text on Android for expandable details

Response

The microservice returns:

Single token: FCM message ID (string)
Multiple tokens: Array of message IDs
Topic: Message ID for topic broadcast

Error Handling

Common errors:

Missing title or subtitle
No targeting field (token, tokens, or topic)
Invalid token format
Invalid Firebase project ID
Network/Firebase connectivity issues

Handle errors appropriately in your application.

13 May 2026