# 模板消息

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

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

关于使用规则,请注意:

  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"
}

参数说明

参数 是否必须 说明
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数据示例如下:

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

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

参数说明

参数 是否必须 说明
access_token 接口调用凭证
template_id_short 模板库中模板的编号,有“TM**”和“OPENTMTM**”等形式,对于类目模板,为纯数字ID
keyword_name_list 选用的类目模板的关键词,按顺序传入,如果为空,或者关键词不在模板库中,会返回40246错误码

返回码说明

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

 {
    "errcode":0,
    "errmsg":"ok",
    "template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"
  }
错误码 说明
40246 需要传入正确的keyword_name_list,保证每个关键词都是来自该模板
40247 历史模板库已经升级为新的类目模板库,请使用类目模板库ID进行添加

# 获取模板列表

获取已添加至账号下所有模板列表,包括类目模板,可在微信公众平台后台中查看模板列表信息。为方便第三方开发者,提供通过接口调用的方式来获取账号下所有模板信息,具体如下:

接口调用请求说明

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} }}",
      "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, 包括类目模板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"
           },
           "client_msg_id":"MSG_000001",
           "data":{

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

参数说明

参数 是否必填 说明
touser 接收者openid
template_id 模板ID
url 模板跳转链接(海外账号没有跳转能力)
miniprogram 跳小程序所需数据,不需跳小程序可不用传该数据
appid 所需跳转到的小程序appid(该小程序appid必须与发模板消息的公众号是绑定关联关系,暂不支持小游戏)
pagepath 所需跳转到小程序的具体页面路径,支持带参数,(示例index?foo=bar),要求该小程序已发布,暂不支持小游戏
data 模板数据
client_msg_id 防重入id。对于同一个openid + client_msg_id, 只发送一条消息,10分钟有效,超过10分钟不保证效果。若无防重入需求,可不填

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

返回码说明

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

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

可能出现的返回码

返回码 含义
43116 该模板因滥用被滥用过多,已被限制下发
40249 不支持下发营销/推广类的消息内容
40250 下发消息内容不规范(包含空值等),建议检查内容规范性后再下发
40251 因历史违规导致平台限制账号调用上限,当前已到达下发上限
40252 正在调用的模板下发的部分内容已进入平台审核流程,在审核完成前,相关内容暂时无法下发

使用效果

# 类目模板消息

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

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

参数类别 参数说明 参数值限制 说明 适用范围
thing.DATA 事物 20个以内字符 可汉字、数字、字母或符号组合 供姓名关键词、地址关键词、机构/组织名关键词选择(如:单位名、银行名、医院名、科室、班级)、品名关键词选择(如:药品名、股票名、课程名、科目名、岗位名)
character_string.DATA 字符串 32位以内数字、字母或符号 可数字、字母或符号组合 供数字/编码/编号/单号/卡号/航班号关键词选择(如:证券编码、设备编号、快递单号、银行卡号、网址)
time.DATA 时间 24小时制时间格式(支持+年月日),支持填时间段,两个时间点之间用“~”符号连接 例如:15:01,或:2019年10月1日 15:01 供时间类关键词选择
amount.DATA 金额 1个币种符号+12位以内纯数字,可带小数,结尾可带“元” 可带小数 供金额类关键词选择
phone_number.DATA 电话 17位以内,数字、符号 电话号码,例:+86-0766-66888866 供电话号码类关键词选择
car_number.DATA 车牌 8位以内,第一位与最后一位可为汉字,其余为字母或数字 车牌号码:粤A8Z888挂 供车牌号码类关键词选择
const.DATA 常量 20位以内字符,超过无法下发注:需枚举(需将内容提交平台审核,审核通过可下发) 只能下发审核通过的字符串和空串 供状态/方式/类型/提醒/说明/详情关键词选择(如:支付状态、排队状态、天气状态、物流状态、用药提醒、还款提醒)

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

参数说明

参数 说明
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 发送状态为发送失败(非用户拒绝)