Developers can use the one-time message subscription authorization feature to enable Weixin users to authorize third-party mobile apps or Official Accounts (see Access Guide), and can therefore get the permission to send a subscription message to authorized users. Authorized users do not have to follow the Official Accounts. Each time when a Weixin user grants authorization, the developer can get the permission to send a message to Service Notification.

How to Use:

1. When a third-party app initiates a one-time subscription authorization request, after a Weixin user grants authorization to the third-party app, Weixin will launch the app and carry such information as the authorized user's openid.
2. The app can push a subscription message to authorized users via an API.

Note: Before accessing one-time message subscription authorization, you must register a developer account on Weixin Open Platform, own an approved mobile app, and obtain the ID of the message template to be sent.

Authorization Process:

Step 1: Get the authorization from a Weixin user and obtain the permission to send a subscription message to users.

The developer must access the SDK provided by Weixin Open Platform to initiate an one-time message subscription authorization request. After accessing the SDK, the developer's mobile app will locally launch the Weixin app for message subscription authorization on the platform. After confirmation by the Weixin user, Weixin will launch the developer's mobile app and carry such information as the authorized user's openid.

Example of the access code of one-time message subscription authorization on the iOS platform (refer to the iOS Access Guide):

WXSubscribeMsgReq \*req = [[WXSubscribeMsgReq alloc] init];
req.scene = scene;
req.templateId = templateId;
req.reserved = reserved;
[WXApi sendReq:req];

Example of the access code of one-time message subscription authorization on the Android platform (refer to the Android Access Guide):

SubscribeMessage.Req req = new SubscribeMessage.Req();
req.scene = scene;
req.templateID = templateID;
req.reserved = reserved;

Parameters

Weixin can be launched to open the one-time message subscription authorization page:

Response Description:

After the user clicks Authorize, the Weixin app is launched and redirects to an authorization interface. The user clicks Confirm or Cancel on this interface. The SDK returns data to the caller via SendAuth Resp.

Response Example:

openid:oyAaTjt-xXvP87pubE4eUOF-ttD4
template_id:7YuTL__ilzyZB9DXcDt2mHx-CAS_E7KtsQkhIGVhhRM
action:confirm
reserved:hello
scene:1000

Parameters

Step 2: Push subscription message template to authorized Weixin users via an API

API Request Description

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/template/subscribe?access_token=ACCESS_TOKEN

POST data example

{
"touser":"OPENID",
"template_id":"TEMPLATE_ID",
"url":"URL",
"scene":"SCENE",
"title":"TITLE",
"data":{
"content":{
"value":"VALUE",
"color":"COLOR"
}
}
}

Parameters

Response Description

After the API is called, a JSON packet is returned. Example of returned JSON packet for a successful request:

{
"errcode":0,
"errmsg":"ok"
}

Appendix: How to get access_token:

The access_token is the globally unique credential for calling APIs. It is required for calls to all APIs, so please save it properly. To store access_token, you need to reserve space for at least 512 characters. The access_token is valid for 2 hours and needs to be updated periodically. Repeated acquisition will invalidate the access_token obtained last time.

Use and generation of the access_token required for calling APIs:

1. To keep the appsecrect confidential, third-party apps need to use a central control server to get and refresh access_token. All the access_token values used by other business logic servers come from this central control server, and should not be updated separately. Otherwise, access_token may be overwritten, which affects services.

2. The validity period of access_token is expressed in the returned expires_in, and its available value is within 7200 seconds. The central control server needs to update access_token in advance based on this validity period. During the update, the central control server may continue to output old access_token values. In this case, the backend of the Official Accounts Platform will ensure that both new and old access_token values are available within a short time after refresh so that third-party services are smoothly transitioned.

3. The validity of access_token may be adjusted in the future. Therefore, the central control server not only needs to actively update access_token on schedule, but also provides an API for passive update of access_token. In this way, when learning that access_token is expired in a call, the service server may trigger the update procedure for access_token.

Developers can get access_token by using AppID and AppSecret to call the API. The AppID and AppSecret of an approved mobile app can be found in Management Center > App Details on the Weixin Open Platform. Store the generated AppSecret properly to avoid reset of AppSecret every time it is generated and viewed on the Official Accounts Platform. The HTTPS protocol should be used to call all Weixin APIs. If a third-party app refreshes the access_token using its business logic node instead of a central control server, the service may not function properly due to the conflict arising therefrom.

API Request Description

HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

Parameters

Response Description

For a successful request, Weixin returns the following JSON packet to the developer:

{"access_token":"ACCESS_TOKEN","expires_in":7200}

Parameters

When an error occurs, Weixin will return an error code and related information. An example of the JSON packet (for an invalid AppID error) is shown below:

{"errcode":40013,"errmsg":"invalid appid"}

Error code