Developers can use the one-time message subscription authorization feature to enable Weixin users to authorize a third-party mobile app (see Access Guide) or an Official Account, and can therefore get the permission to send a subscription message to authorizing users. Authorizing users do not have to follow the Official Account. Each time a Weixin user grants authorization, the developer can get the permission to send a message. (Note: If a user grants authorization multiple times under a scene value, the developer can only send one message. To subscribe to multiple messages, the user needs to grant authorization using different scene values.)
If the user has followed the Official Account, the message will be sent to the Official Account chat; otherwise, the message will be sent to Service Notification.
The process of an Official Account or webpage using the one-time message subscription feature is as follows:
Step 1: Get the authorization from a user and obtain the permission to send a subscription message template to the user.
Ensure that the Weixin Official Account has the permission of message subscription authorization (all verified Official Accounts have the permission that can be viewed in the API permission list on the Official Accounts Platform), and guide the user to open the following link in the Weixin app:
https://mp.weixin.qq.com/mp/subscribemsg?action=get_confirm&appid=wxaba38c7f163da69b&scene=1000&template_id=1uDxHNXwYQfBmXOfPJcjAS3FynHArD8aWMEFNRGSbCc&redirect_url=http%3a%2f%2fsupport.qq.com&reserved=test#wechat_redirect
Parameters
| Parameter | Required | Description |
|---|---|---|
| action | Yes | Enter get_confirm |
| appid | Yes | The unique identifier of the Official Account |
| scene | Yes | The scene parameter is passed after redirection. It is an integer between 0 and 10000, used to identify the subscription scene value. |
| template_id | Yes | The subscription message template ID, which can be viewed in the API permission list at the Official Accounts Platform backend. |
| redirect_url | Yes | Redirect callback URL after authorization. Process the link with UrlEncode. Note: The domain name in the redirect_url must be identical to the registered service domain name which cannot contain any path. You can log in to the Official Account, and set the service domain name in Settings > Official Account Settings > Feature Settings. |
| reserved | No | Used to maintain the request and callback status. It is returned unchanged to the third party after the authorization request. This parameter can be used to prevent any cross-site request forgery (csrf) attack. It is recommended that the third party pass this parameter. It can be checked by setting it to a simple random number plus session. This value must be URL-encoded, with a maximum length of 128 characters comprised of letters (a-z and A-Z) and numbers (0-9). |
| #wechat_redirect | Yes | This parameter is required regardless of whether the page is directly opened or accessed via a 302 redirect. |
Relevant information is returned after the user grants or cancels authorization
If the user grants or cancels authorization, the page will be redirected to:
redirect_url/?openid=OPENID&template_id=TEMPLATE_ID&action=ACTION&scene=SCENE
Parameters
| Parameter | Description |
|---|---|
| openid | A user's unique identifier, which is required only when the user grants authorization. |
| template_id | Subscription message template ID |
| action | Tap action. "confirm": The user grants authorization; "cancel": The user cancels authorization. |
| scene | Subscription scene value |
| reserved | Parameters in the request are returned unchanged |
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",
"miniprogram":{
"appid":"xiaochengxuappid12345",
"pagepath":"index?foo=bar"
},
"scene":"SCENE",
"title":"TITLE",
"data":{
"content":{
"value":"VALUE",
"color":"COLOR"
}
}
}
Parameters
| Parameter | Required | Description |
|---|---|---|
| touser | Yes | The openid of a user who receives messages |
| template_id | Yes | Subscription message template ID |
| url | No | URL to be redirected to after the message is tapped, which must be ICP-licensed. |
| miniprogram | No | The data required for redirection to a Mini Program. If redirection is not needed, this parameter is not required. |
| appid | Yes | The appid of the Mini Program to be redirected to (The appid of the Mini Program must be linked to the Official Account sending the message template, and the Mini Program must be published) |
| pagepath | Yes | The path to the page of the Mini Program to be redirected to. Parameters can be added to the path, for example, index?foo=bar. |
| scene | Yes | Subscription scene value |
| title | Yes | Message title, with a maximum length of 15 characters. |
| data | Yes | Message body. "value" is the message text that consists up to 200 characters, without a fixed format. "\n" is a line break. "color" is the font color of the message and can only be set to one value. |
Note: "url" and "miniprogram" are optional fields. If neither of them is specified, the template will not be redirected; if both of them are specified, the template will first be redirected to the Mini Program. You can choose a redirect type as needed. When the user's Weixin app does not support redirect to Mini Programs, the template will be redirected to a URL.
Response
After the API is called, a JSON packet is returned. Example of returned JSON packet for a successful request:
{
"errcode":0,
"errmsg":"ok"
}