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"
}