# 模板消息

说明：服务号订阅通知功能开启灰度测试，模板消息能力可正常使用

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

关于使用规则，请注意：

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 设置所属行业

2 获取设置的行业信息

3 获得模板ID

4 获取模板列表

5 删除模板

6 发送模板消息

7 事件推送

# 设置所属行业

设置行业可在微信公众平台后台完成，每月可修改行业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"
}

参数说明

行业代码查询

# 获取设置的行业信息

获取账号设置的行业信息。可登录微信公众平台，在公众号后台中查看行业信息。为方便第三方开发者，提供通过接口调用的方式来获取账号所设置的行业信息，具体如下:

接口调用请求说明

http请求方式：GET https://api.weixin.qq.com/cgi-bin/template/get_industry?access_token=ACCESS_TOKEN

参数说明

返回说明

正确调用后的返回示例：

{
    "primary_industry":{"first_class":"运输与仓储","second_class":"快递"},
    "secondary_industry":{"first_class":"IT科技","second_class":"互联网|电子商务"}
}

返回参数说明

# 获得模板ID

从行业模板库选择模板到账号后台，获得模板ID的过程可在微信公众平台后台完成。为方便第三方开发者，提供通过接口调用的方式来获取模板ID，具体如下：

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

支持使用类目模板库的id进行添加，

{
    "template_id_short":"47123",
    "keyword_name_list":["时间","地点","金额"]
 }

参数说明

返回码说明

在调用模板消息接口后，会返回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

参数说明

返回说明

正确调用后的返回示例：

{	
     "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} }}",
      "example": "您已提交领奖申请\n\n领奖金额：xxxx元\n领奖时间：2013-10-10 12:22:22\n银行信息：xx银行(尾号xxxx)\n到账时间：预计xxxxxxx\n\n预计将于xxxx到达您的银行卡"
   }]
}

返回参数说明

# 删除模板

删除模板可在微信公众平台后台完成，为方便第三方开发者，提供通过接口调用的方式来删除某账号下的模板，具体如下：

接口调用请求说明

http请求方式：POST https://api.weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN

POST数据说明如下：

 {
     "template_id" : "Dyvp3-Ff0cnail_CDSzk1fIc6-9lOkxsQE7exTJbwUE"
 }

参数说明

返回说明

在调用接口后，会返回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"
           },
           "client_msg_id":"MSG_000001",
           "data":{

                   "keyword1":{
                       "value":"巧克力"
                   },
                   "keyword2": {
                       "value":"39.8元"
                   },
                   "keyword3": {
                       "value":"2014年9月22日"
                   }
           }
       }

参数说明

注：url和miniprogram都是非必填字段，若都不传则模板无跳转；若都传，会优先跳转至小程序。开发者可根据实际需要选择其中一种跳转方式即可。当用户的微信客户端版本不支持跳小程序时，将会跳转至url。

返回码说明

在调用模板消息接口后，会返回JSON数据包。正常时的返回JSON数据包示例：

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

可能出现的返回码

使用效果

# 类目模板消息

对于类目模板消息，同样使用上述接口进行发送，各参数的含义与要求保持一致。 除此之外，类目模板的模板消息，对于不同参数类型，参数值的格式有相应的要求。

类目模板消息参数值内容限制说明

符号表示除中文、英文、数字外的常见符号，不能带有换行等控制字符。 时间格式支持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

例如，模板的内容为

姓名: {{thing01.DATA}}
金额: {{amount01.DATA}}
行程: {{thing02.DATA}}
日期: {{time01.DATA}}

则对应的json为

{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "data": {
      "thing01": {
          "value": "某某"
      },
      "amount01": {
          "value": "￥100"
      },
      "thing02": {
          "value": "广州至北京"
      },
      "time01": {
          "value": "2019年10月1日 15:00"
      }
  }
}

如果参数不符合要求，会收到如下提示,并指明不符合要求的字段：

{
    "errcode":47003,
    "errmsg":"thing01.DATA is invalid"
}

# 事件推送

在模版消息发送任务完成后，微信服务器会将是否送达成功作为通知，发送到开发者中心中填写的服务器配置地址中。

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>

参数说明

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>

参数说明

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>

参数说明