How to Implement SMS Supplement Service

SMS supplement service is used to deliver key information through SMS when app push cannot reach users in time. Typical causes include network disconnection, background execution restrictions, notification permission being disabled, and long-term device inactivity.

The best practice does not recommend sending both push and SMS by default. Instead, send app push first, wait for the configured period, and send SMS only when the push does not meet the success criteria. This controls SMS cost while improving the final delivery rate of important messages.

Applicable Scenarios

Use SMS supplement for scenarios where users must be notified in time and the SMS cost is acceptable:

• Transaction and account security: login reminders, remote login alerts, payment results, risk control interception, password changes.
• Service fulfillment notifications: order status, delivery exceptions, queue calls, appointment reminders, ticket progress.
• High-value business reminders: membership expiration, important campaign confirmation, contract or billing reminders.
• Push unreachable compensation: notification permission disabled, device offline, unstable vendor channel, long-inactive users.

Do not use it by default for ordinary marketing messages, low-priority operational campaigns, or content that can naturally be exposed in the app. These scenarios are better handled by push frequency control, in-app messages, or inbox messages to avoid disturbing users.

Capability Overview

JPush provides SMS supplement through the sms_message field in the Push API. The original app push process remains unchanged; you only add SMS supplement configuration to the same push request.

There are two modes:

• SMS reissue: set delay_time to a non-zero value. The system sends push first. If the push does not meet the success criteria within the configured time, SMS is sent.
• Concurrent SMS: set delay_time to 0. Push and SMS are sent at the same time. Use this only for rare scenarios that require strong timeliness and strong delivery.

SMS consists of a signature and a body template. Both must be reviewed before use. Since March 2018, SMS supplement must use an approved body template, so temp_id is required in push requests. If the template contains variables, temp_para is also required.

Before Integration

Complete the following preparation before launch:

• Activate SMS service and confirm that the account balance is sufficient. SMS generates additional carrier fees.
• Complete SMS signature and body template review, and confirm signid, temp_id, and template variables.
• Bind the user's mobile number with the device registrationID. You can use the Jiguang server-side Device API or client-side set mobile number APIs.
• Clearly define which business scenarios are allowed to use SMS supplement. Do not enable it for all push messages by default.
• Configure budget, frequency control, alerts, and failure retry policies for SMS supplement.

Related documents:

• Push API sms_message parameter
• Server-side Device API
• Android set mobile number API
• iOS set mobile number
• HarmonyOS set mobile number
• SMS signatures and templates

Recommended Flow

1. Classify Messages First

Not every push needs SMS supplement. Classify messages by business importance:

2. Choose an Appropriate delay_time

delay_time determines how long the system waits for push success:

• 0: concurrent SMS. Push and SMS are sent at the same time.
• 60 to 300: suitable for login, security, payment, queue calls, and other time-sensitive messages.
• 300 to 1800: suitable for orders, logistics, appointments, tickets, and other important messages that do not require second-level delivery.
• No more than 24 hours: values over 24 hours are not supported.

Use SMS reissue as the default mode. Do not use concurrent SMS by default, because it significantly increases cost and may cause duplicate user perception.

3. Configure Template Variables

SMS content should be short, clear, and actionable. Keep only information needed for user decisions, such as the last four digits of an order number, business status, or operation entry guidance.

Pass template variables through temp_para. Variable names must match the variables configured in the SMS template. Do not include sensitive plaintext information, such as full ID numbers, bank card numbers, passwords, or other highly sensitive fields except verification codes.

4. Control Active Filtering

active_filter controls whether active users are filtered before SMS reissue:

• Default true: active filtering is enabled. This suits most scenarios and reduces duplicate disturbance to active users.
• Set to false: active filtering is disabled. Use it only for strong-delivery scenarios, together with stricter business frequency control.

If your server already evaluates user activity, notification permission, and recent touch records, combine those rules with your own decision on whether to disable active filtering.

API Examples

The following example sends push first. If the push does not meet the success criteria within 180 seconds, SMS is sent using the configured template:

          {
  "platform": "all",
  "audience": {
    "registration_id": ["registration_id_1"]
  },
  "notification": {
    "alert": "Your order status has been updated. Please check it in time."
  },
  "sms_message": {
    "delay_time": 180,
    "signid": 12345,
    "temp_id": 67890,
    "temp_para": {
      "order_no": "A1234",
      "status": "delivery exception"
    },
    "active_filter": true
  }
}

        

For concurrent SMS, set delay_time to 0:

          {
  "platform": "all",
  "audience": {
    "registration_id": ["registration_id_1"]
  },
  "notification": {
    "alert": "There is an abnormal login risk on your account. Please confirm immediately."
  },
  "sms_message": {
    "delay_time": 0,
    "signid": 12345,
    "temp_id": 67891,
    "temp_para": {
      "time": "10:30",
      "location": "Shenzhen"
    },
    "active_filter": false
  }
}

        

Success Criteria and Vendor Channel Strategy

Whether SMS reissue is triggered depends on the push success criteria:

• The Jiguang channel uses actual delivery as push success.
• Vendor channels can use configurable criteria, including successful API call, reissue all, no reissue, and delivery receipt. If not configured, successful submission to the vendor server is used by default.

If your business has high final-delivery requirements, contact business support to confirm the vendor channel success criteria. For channels that support delivery receipts, prefer delivery receipt as the success criterion. For channels without stable receipt capability, choose between "reissue all" and "successful API call" based on cost and disturbance risk.

Cost and Disturbance Control

SMS supplement can increase cost and disturb users. Add the following controls on the server side:

• Per-user frequency control: limit SMS supplement count per user within 1 minute, 1 hour, and 24 hours.
• Per-business frequency control: set different limits by business type. Security messages can have higher limits than marketing messages.
• Deduplication: allow only one SMS supplement for the same business event to avoid repeated sends caused by retries.
• Budget control: set daily or campaign-level SMS budget thresholds. After the threshold is reached, degrade to push-only delivery.
• Blacklist control: filter unsubscribed, complained, abnormal, or invalid numbers.
• Nighttime policy: avoid SMS for non-urgent messages at night.

Copywriting and Compliance

• SMS signatures must match enterprise qualification, brand, and business scenario.
• Body templates must be reviewed in advance, and variable content must not change the original meaning of the template.
• Marketing SMS must comply with unsubscribe requirements and should not be the default option for push supplement.
• Copy should clearly explain the business source and user action to avoid being mistaken for spam.
• Avoid including full sensitive information in SMS. When necessary, guide users back to the app or official website for details.

Troubleshooting Checklist

If SMS supplement is not triggered as expected, check the following items:

• Whether SMS service has been activated and the account balance is sufficient.
• Whether the mobile number and registrationID are correctly bound.
• Whether the Push API request contains sms_message.temp_id.
• Whether temp_id, signid, and temp_para match the approved template.
• Whether delay_time is correct, accidentally set to 0, or over 24 hours.
• Whether the push already met the success criteria, so SMS reissue was not needed.
• Whether active_filter filtered recently active users.
• Whether vendor channel success criteria match business expectations.
• Whether the target number is empty, suspended, affected by number portability issues, or intercepted by carriers.
• Whether business-side frequency control, budget limits, or blacklist filtering was triggered.

Recommended Strategy

Use "important message classification + SMS reissue by default + concurrent SMS only for a few scenarios":

• P0 messages: set delay_time to 0 to 180 seconds. Disable active_filter only when necessary, and always apply strict frequency control.
• P1 messages: set delay_time to 180 to 600 seconds. Keep active_filter enabled by default.
• P2/P3 messages: do not use SMS supplement by default. Prefer push strategy, in-app messages, or inbox messages.

This improves the final delivery rate of key business notifications without significantly increasing SMS cost.