微信小程序-小程序订阅消息（四）

一、小程序订阅消息

小程序订阅消息 | 微信开放文档

功能介绍

消息能力是小程序能力中的重要组成，我们为开发者提供了订阅消息能力，以便实现服务的闭环和更优的体验。

• 订阅消息推送位置：服务通知
• 订阅消息下发条件：用户自主订阅
• 订阅消息卡片跳转能力：点击查看详情可跳转至该小程序的页面

消息类型

1. 一次性订阅消息

一次性订阅消息用于解决用户使用小程序后，后续服务环节的通知问题。用户自主订阅后，开发者可不限时间地下发一条对应的服务消息；每条消息可单独订阅或退订。

2. 长期订阅消息

一次性订阅消息可满足小程序的大部分服务场景需求，但线下公共服务领域存在一次性订阅无法满足的场景，如航班延误，需根据航班实时动态来多次发送消息提醒。为便于服务，我们提供了长期性订阅消息，用户订阅一次后，开发者可长期下发多条消息。

目前长期性订阅消息仅向政务民生、医疗、交通、金融、教育等线下公共服务开放，后期将逐步支持到其他线下公共服务业务。

3. 设备订阅消息

设备订阅消息是一种特殊类型的订阅消息，它属于长期订阅消息类型，且需要完成「设备接入」才能使用。

设备订阅消息用于在设备触发某些需要人工介入的事件时（例如设备发生故障、设备耗材不足等），向用户发送消息通知。详见设备订阅消息文档。

使用说明

步骤一：获取模板 ID

在微信公众平台手动配置获取模板 ID：
登录 https://mp.weixin.qq.com 获取模板，如果没有合适的模板，可以申请添加新模板，审核通过后可使用。

步骤二：获取下发权限

一次性订阅消息、长期订阅消息，详见接口 wx.requestSubscribeMessage

设备订阅消息，详见接口 wx.requestSubscribeDeviceMessage

步骤三：调用接口下发订阅消息

一次性订阅消息、长期订阅消息，详见服务端接口 subscribeMessage.send，次数限制：开通支付能力的小程序下发上限是3kw/日，没开通的是1kw/日。

设备订阅消息，详见服务端接口 hardwareDevice.send

注意事项

• 用户勾选 “总是保持以上选择，不再询问” 之后，下次订阅调用 wx.requestSubscribeMessage 不会弹窗，保持之前的选择，修改选择需要打开小程序设置进行修改。

订阅消息事件推送

1、当用户触发订阅消息弹框后，用户的相关行为事件结果会推送至开发者所配置的服务器地址或微信云托管服务。

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>

JSON 格式示例

{
  "ToUserName": "gh_123456789abc",
  "FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
  "CreateTime": "1620973045",
  "MsgType": "event",
  "Event": "subscribe_msg_popup_event",
  "List": [   {
        "TemplateId": "hD-ixGOhYmUfjOnI8MCzQMPshzGVeux_2vzyvQu7O68",
        "SubscribeStatusString": "accept",
        "PopupScene": "0"
    }],
 }

若 "List" 只有一个对象，则只返回对象本身；若 "List" 多于一个对象，则返回一个包含所有对象的数组。

参数说明

参数	说明
ToUserName	小程序帐号ID
FromUserName	用户openid
CreateTime	时间戳
TemplateId	模板id（一次订阅可能有多个id）
SubscribeStatusString	订阅结果（accept接收；reject拒收）
PopupScene	弹框场景，0代表在小程序页面内

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_change_event]]></Event>
    <SubscribeMsgChangeEvent>
        <List>          <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
            <SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
        </List>
    </SubscribeMsgChangeEvent>
</xml>

JSON 格式示例

{
      "ToUserName": "gh_123456789abc",
      "FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
      "CreateTime": "1610968440",
      "MsgType": "event",
      "Event": "subscribe_msg_change_event",
      "List": [  {
                "TemplateId":"BEwX0BOT3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
                "SubscribeStatusString": "reject"
      }],
}

若 "List" 只有一个对象，则只返回对象本身；若 "List" 多于一个对象，则返回一个包含所有对象的数组。

参数说明

参数	说明
ToUserName	小程序帐号ID
FromUserName	用户openid
CreateTime	时间戳
TemplateId	模板id（一次订阅可能有多个id）
SubscribeStatusString	订阅结果（reject拒收）

3、调用订阅消息接口发送消息给用户的最终结果，会推送下发结果事件至开发者所配置的服务器地址或微信云托管服务。

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>

JSON 格式示例

{
    "ToUserName": "gh_123456789abc",
    "FromUserName": "o7esq5PHRGBQYmeNyfG064wEFVpQ",
    "CreateTime": "1620963428",
    "MsgType": "event",
    "Event": "subscribe_msg_sent_event",
    "List": {
        "TemplateId": "BEwX0BO-T3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
        "MsgID": "1864323726461255680",
        "ErrorCode": "0",
        "ErrorStatus": "success"
      }
      
}

参数说明

参数	说明
ToUserName	小程序帐号ID
FromUserName	用户openid
CreateTime	时间戳
TemplateId	模板id（一次订阅可能有多个id）
MsgID	消息id（调用接口时也会返回）
ErrorCode	推送结果状态码（0表示成功）
ErrorStatus	推送结果状态码对应的含义

注意：失败仅包含因异步推送导致的系统失败

订阅消息语音提醒

从基础库 2.18.0 开始支持

当前小程序订阅消息通知与微信消息的通知的提示音是一样的，对于部分订阅消息模板，增加语音提醒能力，播报语料部分字段支持开发者定义。

当开发者调用wx.requestSubscribeMessage时仅订阅1条消息且该模板支持开启语音提醒，用户在订阅时可以选择开启语音提醒。开启后将在接收订阅消息时会同步播报语音提醒。

当用户开启了语音提醒，开发者通过wx.getSetting获取的该模板的订阅状态为'acceptWithAudio'。

订阅弹窗样式如下：

当前支持开启语音提醒的模板及播报语料如下：

标题	类型	类目	播报语料
收款到账通知	长期订阅	金融业-银行、金融业-收单商户服务	小程序示例收款10元，其中“小程序示例”会播报为下发小程序的小程序简称，10会播报为模版中的收款金额

以下情况会导致语音提醒无法播报：

1. 用户将服务通知设置为免打扰
2. 用户开启了手机静音模式或手机音量过低
3. 用户未打开微信新消息通知，可引导用户前往微信-“我”-“设置”-“新消息通知”中打开
4. 用户未打开系统对微信的通知
5. 用户开启了低电量模式
6. 用户版本过低：需要iOS 8.0.6与安卓8.0.3及以上

订阅消息添加提醒

从基础库 2.22.0 开始支持

用户在订阅小程序长期订阅消息时，可以根据自己的使用情况添加提醒。添加后，用户在收到消息时，在微信内将由横幅通知提醒。

当用户添加了提醒，开发者通过wx.getSetting获取的该模板的订阅状态为'acceptWithForcePush'。

订阅弹窗样式如下：

二、wx.requestSubscribeMessage(Object object)

wx.requestSubscribeMessage(Object object) | 微信开放文档

功能描述

调起客户端小程序订阅消息界面，返回用户订阅消息的操作结果。当用户勾选了订阅面板中的“总是保持以上选择，不再询问”时，模板消息会被添加到用户的小程序设置页，通过 wx.getSetting 接口可获取用户对相关模板消息的订阅状态。

注意事项

• 一次性模板 id 和永久模板 id 不可同时使用。
• 低版本基础库2.4.4~2.8.3 已支持订阅消息接口调用，仅支持传入一个一次性 tmplId / 永久 tmplId。
• 2.8.2 版本开始，用户发生点击行为或者发起支付回调后，才可以调起订阅消息界面。
• 2.10.0 版本开始，开发版和体验版小程序将禁止使用模板消息 formId。
• 一次授权调用里，每个tmplId对应的模板标题不能存在相同的，若出现相同的，只保留一个。
• 2.10.0 版本开始，支持订阅语音消息提醒，详情

参数

Object object

属性	类型	默认值	必填	说明
tmplIds	Array		是	需要订阅的消息模板的id的集合，一次调用最多可订阅3条消息（注意：iOS客户端7.0.6版本、Android客户端7.0.7版本之后的一次性订阅/长期订阅才支持多个模板消息，iOS客户端7.0.5版本、Android客户端7.0.6版本之前的一次订阅只支持一个模板消息）消息模板id在[微信公众平台(mp.weixin.qq.com)-功能-订阅消息]中配置。每个tmplId对应的模板标题需要不相同，否则会被过滤。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
errMsg	String	接口调用成功时errMsg值为'requestSubscribeMessage:ok'
[TEMPLATE_ID: string]	String	[TEMPLATE_ID]是动态的键，即模板id，值包括'accept'、'reject'、'ban'、'filter'。'accept'表示用户同意订阅该条id对应的模板消息，'reject'表示用户拒绝订阅该条id对应的模板消息，'ban'表示已被后台封禁，'filter'表示该模板因为模板标题同名被后台过滤。例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用户同意订阅zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE这条消息

object.fail 回调函数

参数

Object res

属性	类型	说明
errMsg	String	接口调用失败错误信息
errCode	Number	接口调用失败错误码

错误码

errCode	errMsg	说明
10001	TmplIds can't be empty	参数传空了
10002	Request list fail	网络问题，请求消息列表失败
10003	Request subscribe fail	网络问题，订阅请求发送失败
10004	Invalid template id	参数类型错误
10005	Cannot show subscribe message UI	无法展示 UI，一般是小程序这个时候退后台了导致的
20001	No template data return, verify the template id exist	没有模板数据，一般是模板 ID 不存在 或者和模板类型不对应 导致的
20002	Templates type must be same	模板消息类型 既有一次性的又有永久的
20003	Templates count out of max bounds	模板消息数量超过上限
20004	The main switch is switched off	用户关闭了主开关，无法进行订阅
20005	This mini program was banned from subscribing messages	小程序被禁封
20013	Reject DeviceMsg Template	不允许通过该接口订阅设备消息

示例代码

wx.requestSubscribeMessage({
  tmplIds: [''],
  success (res) { }
})

三、发送订阅消息

发送订阅消息 | 微信开放文档

发送订阅消息

 调试工具

接口应在服务器端调用，详细说明参见服务端API。

本接口支持云调用。需开发者工具版本 >= 1.02.1904090（最新稳定版下载），wx-server-sdk >= 0.4.0

接口说明

接口英文名

sendMessage

功能描述

该接口用于发送订阅消息。

调用方式

HTTPS 调用

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

云调用

• 出入参和HTTPS调用相同，调用方式可查看云调用说明文档

• 接口方法为: openapi.subscribeMessage.send

第三方调用

• 调用方式以及出入参和HTTPS相同，仅是调用的token不同

• 该接口所属的权限集id为：18

• 服务商获得其中之一权限集授权后，可通过使用authorizer_access_token代商家进行调用

请求参数

属性	类型	必填	说明
access_token	string	是	接口调用凭证，该参数为 URL 参数，非 Body 参数。使用access_token或者authorizer_access_token
template_id	string	是	所需下发的订阅模板id
page	string	否	点击模板卡片后的跳转页面，仅限本小程序内的页面。支持带参数,（示例index?foo=bar）。该字段不填则模板无跳转
touser	string	是	接收者（用户）的 openid
data	string	是	模板内容，格式形如 { "key1": { "value": any }, "key2": { "value": any } }的object
miniprogram_state	string	是	跳转小程序类型：developer为开发版；trial为体验版；formal为正式版；默认为正式版
lang	string	是	进入小程序查看”的语言类型，支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文)，默认为zh_CN

返回参数

属性	类型	说明
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个以内纯汉字，例如：配送中
enum.DATA	枚举值	只能上传枚举值范围内的字段值	调用接口获取参考枚举值

符号表示除中文、英文、数字外的常见符号，不能带有换行等控制字符。 时间格式支持HH:MM:SS或者HH:MM。 日期包含年月日，为y年m月d日，y年m月、m月d日格式，或者用‘-’、‘/’、‘.’符号连接，如2018-01-01，2018/01/01，2018.01.01，2018-01，01-01。 每个模板参数都会以类型为前缀，例如第一个数字模板参数为number01.DATA，第二个为number02.DATA

例如，模板的内容为

姓名: {
   
   {name01.DATA}}
金额: {
   
   {amount01.DATA}}
行程: {
   
   {thing01.DATA}}
日期: {
   
   {date01.DATA}}

则对应的json为

{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "data": {
      "name01": {
          "value": "某某"
      },
      "amount01": {
          "value": "￥100"
      },
      "thing01": {
          "value": "广州至北京"
      } ,
      "date01": {
          "value": "2018-01-01"
      }
  }
}

调用示例

示例说明: HTTPS请求示例

请求数据示例

{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "miniprogram_state":"developer",
  "lang":"zh_CN",
  "data": {
      "number01": {
          "value": "339208499"
      },
      "date01": {
          "value": "2015年01月05日"
      },
      "site01": {
          "value": "TIT创意园"
      } ,
      "site02": {
          "value": "广州市新港中路397号"
      }
  }
} 

返回数据示例

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

示例说明: 云函数调用示例

请求数据示例

const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.subscribeMessage.send({
        "touser": 'OPENID',
        "page": 'index',
        "lang": 'zh_CN',
        "data": {
          "number01": {
            "value": '339208499'
          },
          "date01": {
            "value": '2015年01月05日'
          },
          "site01": {
            "value": 'TIT创意园'
          },
          "site02": {
            "value": '广州市新港中路397号'
          }
        },
        "templateId": 'TEMPLATE_ID',
        "miniprogramState": 'developer'
      })
    return result
  } catch (err) {
    return err
  }
} 

返回数据示例

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

错误码

错误码	错误码取值	解决方案
40001	invalid credential  access_token isinvalid or not latest	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口
40003	invalid openid	不合法的 OpenID ，请开发者确认 OpenID （该用户）是否已关注公众号，或是否是其他公众号的 OpenID
40014	invalid access_token	不合法的 access_token ，请开发者认真比对 access_token 的有效性（如是否过期），或查看是否正在为恰当的公众号调用接口
40037	invalid template_id	不合法的 template_id
85107

四、开放接口

开放接口 | 微信开放文档

开发者可调用接口完成模板选用和消息下发，同时可以授权给第三方开发。

1 addTemplate 选用模板

2 deleteTemplate 删除模板

3 getCategory 获取公众号类目

4 getPubTemplateKeyWordsById 获取模板中的关键词

5 getPubTemplateTitleList 获取所属类目的公共模板

6 getTemplateList 获取私有模板列表

7 send 发送订阅通知

同时可以接收事件推送

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，发送订阅通知时所需

errcode 的合法值

值	说明	最低版本
200014	模版 tid 参数错误
200020	关键词列表 kidList 参数错误
200021	场景描述 sceneDesc 参数错误
200011	此账号已被封禁，无法操作
200013	此模版已被封禁，无法选用
200012	私有模板数已达上限，上限 50 个

请求数据示例

{
  "tid":"401",
  "kidList":[1,2],
  "sceneDesc": "测试数据"
}

返回数据示例

{
  "errmsg": "ok",
  "errcode": 0,
  "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs"
}

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	错误信息

errcode 的合法值

值	说明	最低版本
20001	系统错误（包含该账号下无该模板等）
20002	参数错误
200014	模版 tid 参数错误

请求数据示例

{
  "priTmplId": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"
}

返回数据示例

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

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	类目的中文名

errcode 的合法值

值	说明	最低版本
20001	系统错误

请求数据示例

{
}

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "data": [
       {
           "id": 616,
           "name": "公交"
       }
   ]
}

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	参数类型

errcode 的合法值

值	说明	最低版本
20001	系统错误

请求数据示例

参数在 URL 的 query 里面，例如： https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN&tid=99

{
  "tid": "99"
}

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "data": [
       {
           "kid": 1,
           "name": "物品名称",
           "example": "名称",
           "rule": "thing"
       }
   ]
}

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

errcode 的合法值

值	说明	最低版本
200016	start 参数错误
200017	limit 参数错误
200018	类目 ids 缺失
200019	类目 ids 不合法

请求数据示例

参数在 URL 的 query 里面，例如：https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN&ids="2,616"&start=0&limit=1

{
  "ids": "2,616",
  "start": 0,
  "limit": 1
}

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "count": 55,
   "data": [
       {
           "tid": 99,
           "title": "付款成功通知",
           "type": 2,
           "categoryId": "616"
       }
   ]
}

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 为长期订阅

errcode 的合法值

值	说明	最低版本
20001	系统错误

请求数据示例

{
}

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "data": [
       {
          "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU",
          "title": "报名结果通知",
          "content": "会议时间:{
   
   {date2.DATA}}\n会议地点:{
   
   {thing1.DATA}}\n",
          "example": "会议时间:2016年8月8日\n会议地点:TIT会议室\n",
          "type": 2
       }
   ]
}

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	错误信息

errcode 的合法值

值	说明	最低版本
40003	touser字段openid为空或者不正确
40037	订阅模板id为空不正确
43101	用户拒绝接受消息，如果用户之前曾经订阅过，则表示用户取消了订阅关系
47003	模板参数不准确，可能为空或者不满足规则，errmsg会提示具体是哪个字段出错
41030	page路径不正确

请求数据示例

{
  "touser": "OPENID",
  "template_id": "TEMPLATEID",
  "page": "mp.weixin.qq.com",
  "miniprogram":{
             "appid":"APPID",
             "pagepath":"index?foo=bar"
  },
  "data": {
      "name1": {
          "value": "广州腾讯科技有限公司"
      },
      "thing8": {
          "value": "广州腾讯科技有限公司"
      },
       "time7": {
          "value": "2019年8月8日"
      }
     }
}

返回数据示例

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

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

参数类别	参数说明	参数值限制	说明
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个以内纯汉字，例如：配送中

符号表示除中文、英文、数字外的常见符号，不能带有换行等控制字符。 时间格式支持HH:MM:SS或者HH:MM。 日期包含年月日，为y年m月d日，y年m月、m月d日格式，或者用‘-’、‘/’、‘.’符号连接，如2018-01-01，2018/01/01，2018.01.01，2018-01，01-01。 每个模板参数都会以类型为前缀，例如第一个数字模板参数为number01.DATA，第二个为number02.DATA

例如，模板的内容为

姓名: {
   
   {name01.DATA}}
金额: {
   
   {amount01.DATA}}
行程: {
   
   {thing01.DATA}}
日期: {
   
   {date01.DATA}}

则对应的json为

{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "data": {
      "name01": {
          "value": "某某"
      },
      "amount01": {
          "value": "￥100"
      },
      "thing01": {
          "value": "广州至北京"
      },
      "date01": {
          "value": "2018-01-01"
      }
  }
}

事件推送

用户操作订阅通知弹窗

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

参数	描述
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>

五、报错

1、公众号订阅消息发送报47003错误

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

参数类别	参数说明	参数值限制	说明
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个以内纯汉字，例如：配送中