四、订阅通知

  • 设置订阅功能：服务号可以在图文消息、网页等场景设置订阅功能。
  • 下发条件：用户在前述场景主动订阅后，服务号可通过接口向用户发送订阅通知，如信用卡动账提醒、物流到货通知等。
  • 下发位置：对已关注服务号的用户，通知下发到号内，未关注的下发到服务通知。
  • 跳转能力：可以跳转到公众号图文消息、网页和小程序。
  • 通知类型：分为一次性订阅和长期订阅——
  • 一次性订阅，指用户订阅一次，服务号可不限时间地下发一条对应的订阅通知；
  • 长期订阅，指用户订阅一次，服务号可长期多次下发通知，长期订阅通知仅向政务民生、医疗等公共服务领域开放。

1.addTemplate选用模板

请求地址

POST https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

tid

string

 

是

模板标题 id，可通过getPubTemplateTitleList接口获取，也可登录公众号后台查看获取

kidList

Array.<number>

 

是

开发者自行组合好的模板关键词列表，关键词顺序可以自由搭配（例如 [3,5,4] 或 [4,5,3]），最多支持5个，最少2个关键词组合

sceneDesc

string

 

是

服务场景描述，15个字以内

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

priTmplId

string

添加至帐号下的模板id，发送订阅通知时所需

2.deleteTemplate删除模板

请求地址

POST https://api.weixin.qq.com/wxaapi/newtmpl/deltemplate?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

priTmplId

string

 

是

要删除的模板id

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

3.getCategory获取公众号类目

请求地址

GET https://api.weixin.qq.com/wxaapi/newtmpl/getcategory?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

data

Array.<Objtect>

类目列表

data 的结构

属性

类型

说明

id

number

类目id，查询公共模板库时需要

name

string

类目的中文名

4.getPubTemplateKeyWordsById获取模板中的关键词

请求地址

GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

tid

string

 

是

模板标题 id，可通过接口获取

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

count

number

公共模板列表总数

data

Array.<Objtect>

关键词列表

data 的结构

属性

类型

说明

kid

number

关键词 id，选用模板时需要

name

string

关键词内容

example

string

关键词内容对应的示例

rule

string

参数类型

5.getPubTemplateTitleList获取类目下的公共模板

请求地址

GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

ids

string

 

是

类目 id，多个用逗号隔开

start

number

 

是

用于分页，表示从 start 开始，从 0 开始计数

limit

number

 

是

用于分页，表示拉取 limit 条记录，最大为 30

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

count

number

公共模板列表总数

data

Array.<Objtect>

模板标题列表

data 的结构

属性

类型

说明

tid

number

模版标题 id

title

string

模版标题

type

number

模版类型，2 为一次性订阅，3 为长期订阅

categoryId

number

模版所属类目 id

6.getTemplateList获取私有模板列表

请求地址

GET https://api.weixin.qq.com/wxaapi/newtmpl/gettemplate?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

data

Array.<Objtect>

个人模板列表

data 的结构

属性

类型

说明

priTmplId

string

添加至帐号下的模板 id，发送订阅通知时所需

title

string

模版标题

content

string

模版内容

example

string

模板内容示例

type

number

模版类型，2 为一次性订阅，3 为长期订阅

7.send发送订阅通知

请求地址

POST https://api.weixin.qq.com/cgi-bin/message/subscribe/bizsend?access_token=ACCESS_TOKEN

请求参数

属性

类型

默认值

必填

说明

access_token

string

 

是

接口调用凭证

touser

string

 

是

接收者（用户）的 openid

template_id

string

 

是

所需下发的订阅模板id

page

string

 

否

跳转网页时填写

miniprogram

Array.<Objtect>

 

否

跳转小程序时填写，格式如{ "appid": "pagepath": { "value": any } }

data

Object

 

是

模板内容，格式形如 { "key1": { "value": any }, "key2": { "value": any } }

page 和 miniprogram 同时不填，无跳转；page 和 miniprogram 同时填写，优先跳转小程序；

返回值

Object

返回的 JSON 数据包

属性

类型

说明

errcode

number

错误码

errmsg

string

错误信息

订阅通知参数值内容限制说明

参数类别

参数说明

参数值限制

说明

thing.DATA

事物

20个以内字符

可汉字、数字、字母或符号组合

number.DATA

数字

32位以内数字

只能数字，可带小数

letter.DATA

字母

32位以内字母

只能字母

symbol.DATA

符号

5位以内符号

只能符号

character_string.DATA

字符串

32位以内数字、字母或符号

可数字、字母或符号组合

time.DATA

时间

24小时制时间格式（支持+年月日），支持填时间段，两个时间点之间用“~”符号连接

例如：15:01，或：2019年10月1日 15:01

date.DATA

日期

年月日格式（支持+24小时制时间），支持填时间段，两个时间点之间用“~”符号连接

例如：2019年10月1日，或：2019年10月1日 15:01

amount.DATA

金额

1个币种符号+10位以内纯数字，可带小数，结尾可带“元”

可带小数

phone_number.DATA

电话

17位以内，数字、符号

电话号码，例：+86-0766-66888866

car_number.DATA

车牌

8位以内，第一位与最后一位可为汉字，其余为字母或数字

车牌号码：粤A8Z888挂

name.DATA

姓名

10个以内纯汉字或20个以内纯字母或符号

中文名10个汉字内；纯英文名20个字母内；中文和字母混合按中文名算，10个字内

phrase.DATA

汉字

5个以内汉字

5个以内纯汉字，例如：配送中

8.事件推送

用户操作订阅通知弹窗

场景：用户在图文等场景内订阅通知的操作

参数

描述

ToUserName

公众号微信号

FromUserName

用户 openid

CreateTime

时间戳

TemplateId

模板 id（一次订阅可能有多条通知，带有多个 id）

SubscribeStatusString

用户点击行为（同意、取消发送通知）

PopupScene

场景

SubscribeStatusString 的合法值

值

说明

accept

用户点击“同意”

reject

用户点击“取消”

PopupScene 的合法值

值

说明

1

弹窗来自 H5 页面

2

弹窗来自图文消息

XML 示例

<xml>
    <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
    <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
    <CreateTime>1610969440</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[subscribe_msg_popup_event]]></Event>
    <SubscribeMsgPopupEvent>
        <List>
            <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
            <SubscribeStatusString><![CDATA[accept]]></SubscribeStatusString>
            <PopupScene>2</PopupScene>
        </List>
        <List>
            <TemplateId><![CDATA[9nLIlbOQZC5Y89AZteFEux3WCXRRRG5Wfzkpssu4bLI]]></TemplateId>
            <SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
            <PopupScene>2</PopupScene>
        </List>
    </SubscribeMsgPopupEvent>
</xml>

用户管理订阅通知

场景：用户在服务通知管理页面做通知管理时的操作

参数

描述

ToUserName

公众号微信号

FromUserName

用户 openid

CreateTime

时间戳

TemplateId

模板 id（一次订阅可能有多条通知，带有多个 id）

SubscribeStatusString

用户点击行为（仅推送用户拒收通知）

SubscribeStatusString 的合法值

值

说明

reject

用户点击“取消”

XML 示例

<xml>
    <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
    <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
    <CreateTime>1610969440</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[subscribe_msg_change_event]]></Event>
    <SubscribeMsgChangeEvent>
        <List>
            <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
            <SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
        </List>
    </SubscribeMsgChangeEvent>
</xml>

发送订阅通知

场景：调用 bizsend 接口发送通知

参数

描述

ToUserName

公众号微信号

FromUserName

用户 openid

CreateTime

时间戳

TemplateId

模板 id（一次订阅可能有多条通知，带有多个 id）

MsgID

消息 id

ErrorCode

推送结果状态码（0表示成功）

ErrorStatus

推送结果状态码文字含义

*失败仅包含因异步推送导致的系统失败

XML 示例

<xml>
    <ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
    <FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
    <CreateTime>1610969468</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[subscribe_msg_sent_event]]></Event>
    <SubscribeMsgSentEvent>
        <List>
            <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
            <MsgID>1700827132819554304</MsgID>
            <ErrorCode>0</ErrorCode>
            <ErrorStatus><![CDATA[success]]></ErrorStatus>
        </List>
    </SubscribeMsgSentEvent>
</xml>