Google is committed to advancing racial equity for Black communities. See how.

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 apps on iOS 10 and higher (see iOS documentation for file size limits).

To be able to receive and handle notification images in an iOS 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.