Catch up on everthing we announced at this year's Firebase Summit. Learn more

Send an image in the notification payload

The FCM HTTP v1 API and the Notifications composer support sending image links in the payload of a display notification, for image download to the device after delivery. This functionality supports both images and videos for Apple apps (see Apple documentation for file size limits).

To be able to receive and handle notification images in an Apple app, you must add a Notification Service Extension. The notification service extension allows your app to handle the image delivered in the FCM payload before displaying the notification to the end user.

Set up the notification service extension

To add a service extension, perform the required setup tasks for modifying and presenting notifications in APNs, and then add the FCM extension helper API in NotificationService.m. Specifically, instead of completing the callback with self.contentHandler(self.bestAttemptContent);, complete it with FIRMessaging extensionHelper as shown:

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you wish
    self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent


Build the send request

In your notification send request, set the following ApnsConfig options:

  • fcm_options.image containing the image URL
  • headers({ "mutable-content": 1})

For example:


Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification" : {
      "body" : "This is an FCM notification that displays an image.!",
      "title" : "FCM Notification",
     "apns": {
         "payload": {
             "aps": {
                 "mutable-content": 1
         "fcm_options": {
             "image": "url-to-image"

With mutable-content set as shown, this send request enables the service extension on the receiving client to handle the image delivered in the payload.