# 开放接口

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

同时可以接收事件推送

# 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	Object	否	跳转小程序时填写，格式如{ "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>