Message Override and Recall Best Practices

Message override and message recall can both be used to handle push tasks that have already been created, but they solve different problems:

• Message override: sends a new push to replace a previous push. It is suitable for updating notification content.
• Message recall: recalls a sent push. It is suitable for stopping notifications that are incorrect, expired, or should no longer be displayed.

When designing your business flow, first decide whether the user still needs to see the notification. If only the content has changed, prefer message override. If the notification itself should no longer reach or be displayed to users, use message recall.

Capability Comparison

Message Override

When to Use Override

Message override is suitable for scenarios where the same business event keeps changing. Typical examples:

• Order status changes from "accepted" to "delivering".
• Queue, ticket, or progress notifications need to show the latest state.
• Campaign notification copy or redirect parameters need to be corrected, but users should still receive the latest content.
• Offline users only need to see the final state after coming online, instead of receiving multiple historical state notifications.

Implementation

On Android, when calling Push API v3 to send a new message, set options.override_msg_id to the msg_id returned by the previous push.

          {
  "platform": "android",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "android": {
      "alert": "Your order is being delivered",
      "title": "Order status update"
    }
  },
  "options": {
    "override_msg_id": 1234567890
  }
}

        

Notes

• override_msg_id is the msg_id of the previous push to be overridden.
• The override capability is valid for 1 day. If the corresponding msg_id cannot be found within the valid period, error 1003 is returned and the current message will not be pushed.
• override_msg_id is effective for Android.
• Currently supported channels include the Jiguang channel, Xiaomi, OPPO, vivo, FCM, Honor, Huawei (EMUI 10 and later), and HarmonyOS.
• Offline users receive the overridden message content.
• If the Android notification has already been received and the notification has not been cleared, the new message content replaces the previous notification.

HarmonyOS Override Implementation

HarmonyOS also uses options.override_msg_id. When sending the updated message, set this field to the msg_id returned by the previous push.

          {
  "platform": "hmos",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "hmos": {
      "alert": "Your order is being delivered",
      "title": "Order status update"
    }
  },
  "options": {
    "override_msg_id": 1234567890
  }
}

        

HarmonyOS Notes

• On HarmonyOS, override_msg_id supports both the JPush channel and the HarmonyOS vendor channel.
• For the JPush channel, the app must integrate JPush HarmonyOS SDK v1.5.0 or later.
• The override is valid for 1 day. If the corresponding msg_id cannot be found within the valid period, error 1003 is returned and the current message will not be pushed.
• Always save the msg_id returned by the previous successful push and maintain the override chain for the same business event.

iOS Override Implementation

On iOS, use options.apns_collapse_id as the identifier for updating iOS notifications. If a new APNs notification matches a notification in the current Notification Center with the same apns-collapse-id, APNs updates it with the new notification content and moves it to the top of Notification Center.

          {
  "platform": "ios",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "ios": {
      "alert": "Your order is being delivered",
      "sound": "default"
    }
  },
  "options": {
    "apns_production": true,
    "apns_collapse_id": "order_202607280001"
  }
}

        

iOS Notes

• apns_collapse_id identifies notifications that should update each other. Generate a stable value by business object, such as order ID, queue number, or task ID.
• When multiple pushes use the same apns_collapse_id, APNs attempts to update the old notification with the same identifier in Notification Center.
• apns_collapse_id must not exceed 64 bytes.
• The iOS override effect depends on APNs and the system Notification Center. We recommend adding status validation to the business landing page as well.

Message Recall

When to Use Recall

Message recall is suitable for scenarios where the notification should no longer exist. Typical examples:

• Campaigns, coupons, or tasks have expired and users should no longer click them.
• A notification was sent by mistake or contains incorrect content and should stop reaching users as soon as possible.
• Risk control, review, or operation strategy changes require a sent reminder to be recalled.
• You want to remove, as much as possible, displayed but unclicked notifications from the device notification tray.

Implementation

Call the push recall API and use the target message msgid as the path parameter.

          DELETE /v3/push/{msgid}
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json

        

Full endpoint:

          DELETE https://api.jpush.cn/v3/push/{msgid}

        

A successful request returns HTTP 200 with an empty response body.

If recall fails, HTTP 400 and the failure reason may be returned. Example:

          {
  "error": {
    "code": 1003,
    "message": "msgid doesn't exist"
  }
}

        

Recall Effect

Recall first attempts to cancel the message on the server:

• Android messages can be recalled on the server when they are queued or sending.
• iOS messages can be recalled on the server when they are queued.

For messages that have already been displayed on the device but have not been clicked, the Push SDK attempts device-side recall:

• Android requires JPush Android SDK v3.5.0 or later.
• iOS requires JPush iOS SDK v3.2.8 or later.
• The HarmonyOS JPush channel requires JPush HarmonyOS SDK v1.5.0 or later.
• Supported vendor channels currently include Xiaomi, vivo, and the HarmonyOS vendor channel. Xiaomi uses the latest v3 recall API.
• Before recalling through the HarmonyOS vendor channel, configure the app-level Client ID under HarmonyOS Integration Settings in the Jiguang console. Omitting the Client ID does not affect regular pushes, but HarmonyOS vendor-channel recall will not take effect.

Notes

• The push recall API shares the same rate limit with Push API v3. Calls affect and consume the same quota.
• Recall capability depends on message status, SDK version, vendor capability, and device state. It cannot guarantee that every displayed notification will be removed.
• Device-side recall may no longer work if the notification has already been clicked, cleared, or processed by the system.
• If the business requires strict "no access" behavior, add status validation to the landing page, campaign page, or backend business API so users cannot continue through historical links.

Selection Recommendations

Prefer Message Override

When the goal is to let users see the latest content, prefer message override. Examples include order status, delivery progress, queue progress, and to-do status updates.

Recommended flow:

• Android: save the msg_id returned by the first push. For later updates of the same business event, set the previous msg_id in options.override_msg_id.
• HarmonyOS: save the msg_id returned by the first push and use options.override_msg_id for later updates. The JPush channel requires JPush HarmonyOS SDK v1.5.0 or later.
• iOS: generate a stable apns_collapse_id for the same business event, and keep using the same value when updating the notification.
• If Android override returns 1003, it means a valid override cannot be completed. You can send a normal push again if required by the business.

Prefer Message Recall

When the goal is to make users no longer see or click the message as much as possible, prefer message recall. Examples include mistaken sends, expired content, cancellations, and risk-control blocks.

Recommended flow:

• Save the msgid of the message that may need to be recalled.
• Call the push recall API as early as possible. The earlier the recall, the higher the chance of server-side recall success.
• On HarmonyOS, use JPush HarmonyOS SDK v1.5.0 or later for the JPush channel. For the HarmonyOS vendor channel, first configure the app-level Client ID in the Jiguang console.
• Add fallback validation for important flows, such as landing page status checks, campaign validity checks, and order status checks.

Recommended Business Flow

1. Send the first business notification and save the mapping between the returned msg_id and the business order ID.
2. When business status changes, decide whether to update the content or cancel the notification.
3. To update content, call Push API v3. Set options.override_msg_id for Android and HarmonyOS, and set options.apns_collapse_id for iOS.
4. To cancel the notification, call the push recall API.
5. Add status validation to the notification landing page or business API so users clicking historical notifications still see the correct result.

Related Documents

• Push API v3 - override_msg_id
• Push API v3 - apns_collapse_id
• Push API v3 Advanced Features - Push Recall API
• HarmonyOS Vendor Channel Parameter Application Guide
• HarmonyOS SDK Integration Guide