Mastering WeChat Mini Program Subscription Messages: From Setup to Code

What Is a Subscription Message

A subscription message is a one‑way push that can be sent without user interaction, but it requires explicit user authorization. It differs from service notifications because the user must grant permission before the developer can send predefined information.

One‑way push: messages flow from developer to user.

User authorization required: each send must be preceded by user consent.

Message limit: only one message can be sent per subscription.

Typical Use Cases

Logistics notifications: inform users about package delivery status.

Service appointments: notify users of changes to scheduled services.

Event reminders: push notifications for successful event registration or upcoming events.

Order status updates: update users on payment, shipment, and other order states.

Implementation Process

01 Apply for a Template in the WeChat Public Platform

In the Mini Program management console:

Navigate to Basic Features → Subscription Messages and select Enable .

Search for or create a template that matches your needs.

Save the template and record its Template ID for later use.

You can use an already approved template or create a new one and wait for review.

Template keywords can be edited after selection.

02 Configure Message Push on the Backend

In the Mini Program management console:

Go to Development → Interface Settings and enable the Message Push feature.

Set the push URL and Token; this endpoint receives event notifications from WeChat servers.

Verify the configuration, for example by sending a test message and confirming receipt.

Why configure push?

The push feature provides event notifications such as user subscription actions and template message delivery results. When a user subscribes or a message fails, WeChat sends an event to the configured URL, allowing developers to monitor status in real time.

You can test the API endpoint with the WeChat Open Platform API Explorer: https://developers.weixin.qq.com/apiExplorer

03 Frontend Requests User Subscription

Call the wx.requestSubscribeMessage API to ask the user for permission.

Example code:

/**
 * Request subscription messages from the user
 */
export function requestSubscribeMessage(templateIds: string[]) {
  return new Promise((resolve, reject) => {
    wx.requestSubscribeMessage({
      tmplIds: templateIds,
      success(res) {
        // Filter accepted template IDs
        const acceptedTemplateIds = Object.entries(res)
          .filter(([_, status]) => status === 'accept')
          .map(([templateId, _]) => templateId);
        resolve(acceptedTemplateIds); // return array of accepted IDs
      },
      fail(err) {
        console.error('Subscription request failed:', err);
        reject(err);
      }
    });
  });
}

Note:

Users can choose “Always keep this choice, do not ask again”; after that the front‑end will no longer show the dialog.

Template IDs must be created and enabled in the management console beforehand.

04 Server Sends Subscription Message

Use the official API endpoint: https://api.weixin.qq.com/cgi-bin/message/subscribe/send to deliver the message.

Design considerations:

Bind each chosen template ID with a specific order number; otherwise the request may be rejected by WeChat.

Subscription messages are one‑time; if the user does not re‑authorize, further sends are impossible.

Many subscription messages are triggered after an event (e.g., order status change) following the user’s template selection.

Send asynchronous event notifications after the database transaction commits, optionally with retry logic.

Ensure the fields in the payload exactly match the template fields to avoid errors.

Example server‑side code (Java Spring):

@Async
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onAppointmentSigned(AppointmentSignedEvent event) {
    try {
        AppointmentOrderDetailDTO appointmentOrderDetail = appointmentOrderQueryExecutor.getDetail(event.getOrderId());
        UserAccountDTO userAccountDTO = userAccountQueryExecutor.getDetail(Long.valueOf(appointmentOrderDetail.getUserId()));

        WxSubscribeSignAppointmentCmd subscribeSignAppointmentCmd = WxSubscribeSignAppointmentCmd.builder()
                .openId(userAccountDTO.getOpenId())
                .orderNo(event.getOrderId())
                .userName(userAccountDTO.getAccountName())
                .coachName(appointmentOrderDetail.getCoachName())
                .courseName(appointmentOrderDetail.getCourseName())
                .signTime(appointmentOrderDetail.getSignTime().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")))
                .build();
        messageCmdExecutor.sendAppointmentSignMessage(subscribeSignAppointmentCmd);
    } catch (Exception e) {
        log.warn("Failed to send appointment sign subscription message!", e);
    }
}

Conclusion

Subscription messages are a key capability of WeChat Mini Programs that can greatly improve user experience. Implementers must follow WeChat’s interface specifications and privacy requirements strictly to ensure stability and maintain user trust.