模板消息接口 - 微信公众号开发手册

模板消息接口

模板消息仅用于公众号向用户发送重要的服务通知，只能用于符合其要求的服务场景中，如信用卡刷卡通知，商品购买成功通知等。不支持广告等营销类消息以及其它所有可能对用户造成骚扰的消息。

关于使用规则，请注意：

1、所有服务号都可以在功能->添加功能插件处看到申请模板消息功能的入口，但只有认证后的服务号才可以申请模板消息的使用权限并获得该权限；
2、需要选择公众账号服务所处的2个行业，每月可更改1次所选行业；
3、在所选择行业的模板库中选用已有的模板进行调用；
4、每个账号可以同时使用25个模板。
5、当前每个账号的模板消息的日调用上限为10万次，单个模板没有特殊限制。【2014年11月18日将接口调用频率从默认的日1万次提升为日10万次，可在MP登录后的开发者中心查看】。当账号粉丝数超过10W/100W/1000W时，模板消息的日调用上限会相应提升，以公众号MP后台开发者中心页面中标明的数字为准。

关于接口文档，请注意：

1、模板消息调用时主要需要模板ID和模板中各参数的赋值内容；
2、模板中参数内容必须以".DATA"结尾，否则视为保留字；
3、模板保留符号"{{ }}"。

设置所属行业

设置行业可在MP中完成，每月可修改行业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

获取设置的行业信息

获取帐号设置的行业信息。可在MP官网中查看行业信息，为方便第三方开发者，提供通过接口调用的方式来获取帐号所设置的行业信息，具体如下:

接口调用请求说明

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的过程可在MP中完成。为方便第三方开发者，提供通过接口调用的方式来获取模板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"
       }

获取模板列表

获取已添加至帐号下所有模板列表，可在MP中查看模板列表信息，为方便第三方开发者，提供通过接口调用的方式来获取帐号下所有模板信息，具体如下:

接口调用请求说明

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	是	模板示例

删除模板

删除模板可在MP中完成，为方便第三方开发者，提供通过接口调用的方式来删除某帐号下的模板，具体如下：

接口调用请求说明

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",            
           "data":{
                   "first": {
                       "value":"恭喜你购买成功！",
                       "color":"#173177"
                   },
                   "keynote1":{
                       "value":"巧克力",
                       "color":"#173177"
                   },
                   "keynote2": {
                       "value":"39.8元",
                       "color":"#173177"
                   },
                   "keynote3": {
                       "value":"2014年9月22日",
                       "color":"#173177"
                   },
                   "remark":{
                       "value":"欢迎再次购买！",
                       "color":"#173177"
                   }
           }
       }

参数说明

参数	是否必填	说明
touser	是	接收者openid
template_id	是	模板ID
url	否	模板跳转链接
data	是	模板数据

返回码说明

在调用模板消息接口后，会返回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	发送状态为发送失败（非用户拒绝）