模板消息接口
模板消息仅用于公众号向用户发送重要的服务通知,只能用于符合其要求的服务场景中,如信用卡刷卡通知,商品购买成功通知等。不支持广告等营销类消息以及其它所有可能对用户造成骚扰的消息。
关于使用规则,请注意:
1、所有服务号都可以在功能->添加功能插件处看到申请模板消息功能的入口,但只有认证后的服务号才可以申请模板消息的使用权限并获得该权限;
2、需要选择公众账号服务所处的2个行业,每月可更改1次所选行业;
3、在所选择行业的模板库中选用已有的模板进行调用;
4、每个账号可以同时使用25个模板。
5、当前每个账号的模板消息的日调用上限为10万次,单个模板没有特殊限制。【2014年11月18日将接口调用频率从默认的日1万次提升为日10万次,可在MP登录后的开发者中心查看】。当账号粉丝数超过10W/100W/1000W时,模板消息的日调用上限会相应提升,以公众号MP后台开发者中心页面中标明的数字为准。
关于接口文档,请注意:
1、模板消息调用时主要需要模板ID和模板中各参数的赋值内容;
2、模板中参数内容必须以".DATA"结尾,否则视为保留字;
3、模板保留符号"{{ }}"。
目录
设置所属行业
设置行业可在微信公众平台后台完成,每月可修改行业1次,帐号仅可使用所属行业中相关的模板,为方便第三方开发者,提供通过接口调用的方式来修改账号所属行业,具体如下:
接口调用请求说明
http请求方式: POST
https://api.weixin.qq.com/cgi-bin/template/api_set_industry?access_token=ACCESS_TOKEN
POST数据说明
POST数据示例如下:
{
"industry_id1":"1",
"industry_id2":"4"
}
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
industry_id1 | 是 | 公众号模板消息所属行业编号 |
industry_id2 | 是 | 公众号模板消息所属行业编号 |
行业代码查询
主行业 | 副行业 | 代码 |
---|---|---|
IT科技 | 互联网/电子商务 | 1 |
IT科技 | IT软件与服务 | 2 |
IT科技 | IT硬件与设备 | 3 |
IT科技 | 电子技术 | 4 |
IT科技 | 通信与运营商 | 5 |
IT科技 | 网络游戏 | 6 |
金融业 | 银行 | 7 |
金融业 | 基金理财信托 | 8 |
金融业 | 保险 | 9 |
餐饮 | 餐饮 | 10 |
酒店旅游 | 酒店 | 11 |
酒店旅游 | 旅游 | 12 |
运输与仓储 | 快递 | 13 |
运输与仓储 | 物流 | 14 |
运输与仓储 | 仓储 | 15 |
教育 | 培训 | 16 |
教育 | 院校 | 17 |
政府与公共事业 | 学术科研 | 18 |
政府与公共事业 | 交警 | 19 |
政府与公共事业 | 博物馆 | 20 |
政府与公共事业 | 公共事业非盈利机构 | 21 |
医药护理 | 医药医疗 | 22 |
医药护理 | 护理美容 | 23 |
医药护理 | 保健与卫生 | 24 |
交通工具 | 汽车相关 | 25 |
交通工具 | 摩托车相关 | 26 |
交通工具 | 火车相关 | 27 |
交通工具 | 飞机相关 | 28 |
房地产 | 建筑 | 29 |
房地产 | 物业 | 30 |
消费品 | 消费品 | 31 |
商业服务 | 法律 | 32 |
商业服务 | 会展 | 33 |
商业服务 | 中介服务 | 34 |
商业服务 | 认证 | 35 |
商业服务 | 审计 | 36 |
文体娱乐 | 传媒 | 37 |
文体娱乐 | 体育 | 38 |
文体娱乐 | 娱乐休闲 | 39 |
印刷 | 印刷 | 40 |
其它 | 其它 | 41 |
获取设置的行业信息
获取帐号设置的行业信息。可登录微信公众平台,在公众号后台中查看行业信息。为方便第三方开发者,提供通过接口调用的方式来获取帐号所设置的行业信息,具体如下:
接口调用请求说明
http请求方式:GET
https://api.weixin.qq.com/cgi-bin/template/get_industry?access_token=ACCESS_TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
返回说明
正确调用后的返回示例:
{
"primary_industry":{"first_class":"运输与仓储","second_class":"快递"},
"secondary_industry":{"first_class":"IT科技","second_class":"互联网|电子商务"}
}
返回参数说明
参数 | 是否必填 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
primary_industry | 是 | 帐号设置的主营行业 |
secondary_industry | 是 | 帐号设置的副营行业 |
获得模板ID
从行业模板库选择模板到帐号后台,获得模板ID的过程可在微信公众平台后台完成。为方便第三方开发者,提供通过接口调用的方式来获取模板ID,具体如下:
接口调用请求说明
http请求方式: POST
https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
POST数据说明
POST数据示例如下:
{
"template_id_short":"TM00015"
}
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
template_id_short | 是 | 模板库中模板的编号,有“TM**”和“OPENTMTM**”等形式 |
返回码说明
在调用模板消息接口后,会返回JSON数据包。正常时的返回JSON数据包示例:
{
"errcode":0,
"errmsg":"ok",
"template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"
}
获取模板列表
获取已添加至帐号下所有模板列表,可在微信公众平台后台中查看模板列表信息。为方便第三方开发者,提供通过接口调用的方式来获取帐号下所有模板信息,具体如下:
接口调用请求说明
http请求方式:GET
https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=ACCESS_TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
返回说明
正确调用后的返回示例:
{
"template_list": [{
"template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s",
"title": "领取奖金提醒",
"primary_industry": "IT科技",
"deputy_industry": "互联网|电子商务",
"content": "{ {result.DATA} }\n\n领奖金额:{ {withdrawMoney.DATA} }\n领奖 时间:{ {withdrawTime.DATA} }\n银行信息:{ {cardInfo.DATA} }\n到账时间: { {arrivedTime.DATA} }\n{ {remark.DATA} }",
"example": "您已提交领奖申请\n\n领奖金额:xxxx元\n领奖时间:2013-10-10 12:22:22\n银行信息:xx银行(尾号xxxx)\n到账时间:预计xxxxxxx\n\n预计将于xxxx到达您的银行卡"
}]
}
返回参数说明
参数 | 是否必填 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
template_id | 是 | 模板ID |
title | 是 | 模板标题 |
primary_industry | 是 | 模板所属行业的一级行业 |
deputy_industry | 是 | 模板所属行业的二级行业 |
content | 是 | 模板内容 |
example | 是 | 模板示例 |
删除模板
删除模板可在微信公众平台后台完成,为方便第三方开发者,提供通过接口调用的方式来删除某帐号下的模板,具体如下:
接口调用请求说明
http请求方式:POST
https://api.weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN
POST数据说明如下:
{
"template_id" : "Dyvp3-Ff0cnail_CDSzk1fIc6-9lOkxsQE7exTJbwUE"
}
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 接口调用凭证 |
template_id | 是 | 公众帐号下模板消息ID |
返回说明
在调用接口后,会返回JSON数据包。正常时的返回JSON数据包示例:
{
"errcode" : 0,
"errmsg" : "ok"
}
发送模板消息
接口调用请求说明
http请求方式: POST
https://api.weixin.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN
POST数据说明
POST数据示例如下:
{
"touser":"OPENID",
"template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
"url":"http://weixin.qq.com/download",
"miniprogram":{
"appid":"xiaochengxuappid12345",
"pagepath":"index?foo=bar"
},
"data":{
"first": {
"value":"恭喜你购买成功!",
"color":"#173177"
},
"keyword1":{
"value":"巧克力",
"color":"#173177"
},
"keyword2": {
"value":"39.8元",
"color":"#173177"
},
"keyword3": {
"value":"2014年9月22日",
"color":"#173177"
},
"remark":{
"value":"欢迎再次购买!",
"color":"#173177"
}
}
}
参数说明
参数 | 是否必填 | 说明 |
---|---|---|
touser | 是 | 接收者openid |
template_id | 是 | 模板ID |
url | 否 | 模板跳转链接(海外帐号没有跳转能力) |
miniprogram | 否 | 跳小程序所需数据,不需跳小程序可不用传该数据 |
appid | 是 | 所需跳转到的小程序appid(该小程序appid必须与发模板消息的公众号是绑定关联关系,暂不支持小游戏) |
pagepath | 否 | 所需跳转到小程序的具体页面路径,支持带参数,(示例index?foo=bar),暂不支持小游戏 |
data | 是 | 模板数据 |
color | 否 | 模板内容字体颜色,不填默认为黑色 |
注:url和miniprogram都是非必填字段,若都不传则模板无跳转;若都传,会优先跳转至小程序。开发者可根据实际需要选择其中一种跳转方式即可。当用户的微信客户端版本不支持跳小程序时,将会跳转至url。
返回码说明
在调用模板消息接口后,会返回JSON数据包。正常时的返回JSON数据包示例:
{
"errcode":0,
"errmsg":"ok",
"msgid":200228332
}
使用效果
事件推送
在模版消息发送任务完成后,微信服务器会将是否送达成功作为通知,发送到开发者中心中填写的服务器配置地址中。
1、送达成功时,推送的XML如下:
<xml>
<ToUserName>< ![CDATA[gh_7f083739789a] ]></ToUserName>
<FromUserName>< ![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8] ]></FromUserName>
<CreateTime>1395658920</CreateTime>
<MsgType>< ![CDATA[event] ]></MsgType>
<Event>< ![CDATA[TEMPLATESENDJOBFINISH] ]></Event>
<MsgID>200163836</MsgID>
<Status>< ![CDATA[success] ]></Status>
</xml>
参数说明
参数 | 说明 |
---|---|
ToUserName | 公众号微信号 |
FromUserName | 接收模板消息的用户的openid |
CreateTime | 创建时间 |
MsgType | 消息类型是事件 |
Event | 事件为模板消息发送结束 |
MsgID | 消息id |
Status | 发送状态为成功 |
2、送达由于用户拒收(用户设置拒绝接收公众号消息)而失败时,推送的XML如下:
<xml>
<ToUserName>< ![CDATA[gh_7f083739789a] ]></ToUserName>
<FromUserName>< ![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8] ]></FromUserName>
<CreateTime>1395658984</CreateTime>
<MsgType>< ![CDATA[event] ]></MsgType>
<Event>< ![CDATA[TEMPLATESENDJOBFINISH] ]></Event>
<MsgID>200163840</MsgID>
<Status>< ![CDATA[failed:user block] ]></Status>
</xml>
参数说明
参数 | 说明 |
---|---|
ToUserName | 公众号微信号 |
FromUserName | 接收模板消息的用户的openid |
CreateTime | 创建时间 |
MsgType | 消息类型是事件 |
Event | 事件为模板消息发送结束 |
MsgID | 消息id |
Status | 发送状态为用户拒绝接收 |
3、送达由于其他原因失败时,推送的XML如下:
<xml>
<ToUserName>< ![CDATA[gh_7f083739789a] ]></ToUserName>
<FromUserName>< ![CDATA[oia2TjuEGTNoeX76QEjQNrcURxG8] ]></FromUserName>
<CreateTime>1395658984</CreateTime>
<MsgType>< ![CDATA[event] ]></MsgType>
<Event>< ![CDATA[TEMPLATESENDJOBFINISH] ]></Event>
<MsgID>200163840</MsgID>
<Status>< ![CDATA[failed: system failed] ]></Status>
</xml>
参数说明
参数 | 说明 |
---|---|
ToUserName | 公众号微信号 |
FromUserName | 接收模板消息的用户的openid |
CreateTime | 创建时间 |
MsgType | 消息类型是事件 |
Event | 事件为模板消息发送结束 |
MsgID | 消息id |
Status | 发送状态为发送失败(非用户拒绝) |