# 开放接口

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

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>