Message templates are only used by Official Accounts to send important service notifications to users in service scenarios that meet their requirements, such as credit card payment notifications, and product purchase success notifications. Promotional messages such as ads and all the other messages that may harass users are not supported.

Notes about the usage rules:

1. All Service Accounts can view the entry for applying for the message template feature in **Feature** > **Add Feature Plug-in**, but only verified Service Accounts can apply for and obtain the permission to use message templates.
2. An Official Account should select 2 industries in which the Official Account serves, and can change the industries once each month.
3. An Official Account should call the existing templates in the template libraries of the selected industries.
4. Each account can use 25 templates at the same time.
5. Each account can call message templates up to 100,000 times per day, with no certain limit on the number of calls to a single template. (The default call frequency limit of APIs was increased from 10,000 times/day to 100,000 times/day on November 18, 2014, which can be viewed in the Developer Center on the Weixin Official Accounts Platform). When the number of followers of an account exceeds 100,000/1,000,000/10,000,000, the daily call limit of message templates will be increased, as indicated in the Developer Center on the Weixin Official Accounts Platform.

Notes about the API documentation:

1. The template ID and the values of parameters in the template are required to call a message template.
2. The parameter values in the template must end with ".DATA"; otherwise, the parameters will be considered as reserved words.
3. The symbols "{{ }}" are kept in templates.

Contents

1 Setting Industries

2 Getting Configured Industry Information

3 Getting Template ID

4 Getting Template List

5 Deleting Templates

6 Sending Message Templates

7 Event Push

# Setting Industries

By setting an industry on the Weixin Official Accounts Platform, an Official Account can change the industry once a month and can only use relevant templates in the industry. Third-party developers can use this API to change the industries:

API request format

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/template/api_set_industry?access_token=ACCESS_TOKEN

POST data description

POST data example:

{
    "industry_id1":"1",
    "industry_id2":"4"
}

Parameters:

Parameter Required Description
access_token Yes API call credentials
industry_id1 Yes The code of the industry of the Official Account message template
industry_id2 Yes The code of the industry of the Official Account message template

Industry code list

Primary Industry Secondary Industry Code
IT Internet/E-commerce 1
IT IT software and services 2
IT IT hardware and devices 3
IT Electronic technology 4
IT Communications and operators 5
IT Online games 6
Financial Banking 7
Financial Fund management and trust 8
Financial Insurance 9
Catering Catering 10
Hotel and tourism Hotel 11
Hotel and tourism Tourism 12
Transportation and warehousing Express delivery 13
Transportation and warehousing Logistics 14
Transportation and warehousing Warehousing 15
Education Training 16
Education Colleges 17
Government and public utilities Academic research 18
Government and public utilities Traffic police 19
Government and public utilities Museum 20
Government and public utilities Public utilities and non-profit organizations 21
Medical care Pharmaceutical and medical 22
Medical care Care and beauty 23
Medical care Health and hygiene 24
Vehicles Automobile related 25
Vehicles Motorcycle related 26
Vehicles Train related 27
Vehicles Airplane related 28
Real estate Construction 29
Real estate Property management 30
Consumer goods Consumer goods 31
Commercial services Legal 32
Commercial services Exhibition 33
Commercial services Intermediary services 34
Commercial services Certification 35
Commercial services Audit 36
Sports and recreation Media 37
Sports and recreation Sports 38
Sports and recreation Entertainment and leisure 39
Printing Printing 40
Others Others 41

# Getting Configured Industry Information

This API is used to get the industry information set by Official Accounts. You can view the industry information on the Weixin Official Accounts Platform.

API request format

HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/template/get_industry?access_token=ACCESS_TOKEN

Parameters

Parameter Required Description
access_token Yes API call credentials

Response

Example of return result for a successful call:

{
    "primary_industry":{"first_class":"Transportation and warehousing","second_class":"Express delivery"},
    "secondary_industry":{"first_class":"IT","second_class":"Internet|E-commerce"}
}

Response parameters

Parameter Required Description
access_token Yes API call credentials
primary_industry Yes The primary industry of the Official Account
secondary_industry Yes The secondary industry of the Official Account

# Getting Template ID

The process of selecting a template from the industry template library to the account backend and the process of obtaining the template ID can be completed on the Weixin Official Accounts Platform. Third-party developers can use this API to get the template ID:

API request format

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN

POST data description

POST data example:

{
    "template_id_short":"TM00015"
 }

Parameters:

Parameter Required Description
access_token Yes API call credentials
template_id_short Yes ID of a template in the template library, in the formats of "TM**" and "OPENTMTM**".

Error codes

After the Message Template API is called, a JSON packet is returned. Example of returned JSON packet for a successful request:

 {
     "errcode":0,
     "errmsg":"ok",
      "template_id":"Doclyl5uP7Aciu-qZ7mJNPtWkbkYnWBWVja26EGbNyk"
  }

# Getting Template List

This API is used to get the list of all templates added to an account. You can view the template list on the Weixin Official Accounts Platform.

API request format

HTTP Request method: GET
https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=ACCESS_TOKEN

Parameters

Parameter Required Description
access_token Yes API call credentials

Response

Example of return result for a successful call:

{	
     "template_list": [{
      "template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s",
      "title": "Bonus claiming notification",
      "primary_industry": "IT",
      "deputy_industry": "Internet|E-commerce",
      "content": "{ {result.DATA} }\n\nAmount to be claimed:{ {withdrawMoney.DATA} }\nTime of claiming:    { {withdrawTime.DATA} }\nBank information:{ {cardInfo.DATA} }\nTime of receiving:  { {arrivedTime.DATA} }\n{ {remark.DATA} }",
      "example": "You have submitted a bonus claiming application\n\nAmount to be claimed: xxxx CNY\nTime of claiming: 2013-10-10 12:22:22\nBank information: xx Bank (Last numbers: xxxx)\nTime of receiving: Expected at xxxxxxx\n\nIt is expected to be received by your bank card at xxxx"
   }]
}

Response parameters

Parameter Required Description
access_token Yes API call credentials
template_id Yes Template ID
title Yes Template title
primary_industry Yes The industry of the template
deputy_industry Yes The sub-industry of the template
content Yes Template content
example Yes Template sample

# Deleting Templates

This API is used to delete templates under an account on the Weixin Official Accounts Platform.

API request format

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN

POST data description:

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

Parameters

Parameter Required Description
access_token Yes API call credentials
template_id Yes ID of the message template under the Official Account

Response

After the API is called, a JSON packet is returned. Example of returned JSON packet for a successful request:

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

# Sending Message Templates

API request format

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN

POST data description

POST data example:

      {
           "touser":"OPENID",
           "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
           "url":"http://weixin.qq.com/download",  
           "miniprogram":{
             "appid":"xiaochengxuappid12345",
             "pagepath":"index?foo=bar"
           },          
           "data":{
                   "first": {
                       "value":"Purchase succeeded!",
                       "color":"#173177"
                   },
                   "keyword1":{
                       "value":"Chocolate",
                       "color":"#173177"
                   },
                   "keyword2": {
                       "value":"39.8 CNY",
                       "color":"#173177"
                   },
                   "keyword3": {
                       "value":"2014-9-22",
                       "color":"#173177"
                   },
                   "remark":{
                       "value":"Welcome to purchase more!",
                       "color":"#173177"
                   }
           }
       }

Parameters:

Parameter Required Description
touser Yes Recipient's openid
template_id Yes Template ID
url No The URL to which the template is redirected (redirection is not available for foreign accounts)
miniprogram No The data required for redirection to a Mini Program. If redirection is not needed, this parameter is not required.
appid Yes The appid of the Mini Program to be redirected to (The appid of the Mini Program must be linked to the Official Account sending the message template. Mini Games are not supported.)
pagepath No The path to the page of the Mini Program to be redirected to. Parameters can be added to the path, for example, index?foo=bar. The Mini Program must be published, and Mini Games are not supported.
data Yes Template data
color No The font color of the template content. If it is not specified, black is used by default.

Note: "url" and "miniprogram" are optional fields. If neither of them is specified, the template will not be redirected; if both of them are specified, the template will first be redirected to the Mini Program. You can choose a redirect type as needed. When the user's Weixin app does not support redirect to Mini Programs, the template will be redirected to a URL.

Error codes

After the Message Template API is called, a JSON packet is returned. Example of returned JSON packet for a successful request:

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

Effect

# Event Push

After a message template sending task is completed, the Weixin server will send a notification indicating the success or failure of the task to the server address entered in the Developer Center.

  1. The XML pushed for a successful task:
   <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>

Parameters:

Parameter Description
ToUserName The Weixin ID of the Official Account
FromUserName The openid of the user receiving the message template
CreateTime Creation time
MsgType Message type (event)
Event The event is that the message template is sent
MsgID Message ID
Status Sending status (successful)
  1. The XML pushed for a failed task due to user's rejection (the user has set to reject Official Accounts messages):

``

1395658984


200163840



Parameters:



|  Parameter |  Description |
| --- | --- |
| ToUserName |  The Weixin ID of the Official Account |
| FromUserName |  The openid of the user receiving the message template |
| CreateTime |  Creation time |
| MsgType |  Message type (event) |
| Event |  The event is that the message template is sent |
| MsgID |  Message ID |
| Status |  Sending status (failed due to user's rejection) |



3. The XML pushed for a failed task due to other reasons:




1395658984


200163840



Parameters:



| Parameter | Description |
| --- | --- |
| ToUserName | The Weixin ID of the Official Account |
| FromUserName | The openid of the user receiving the message template |
| CreateTime | Creation time |
| MsgType | Message type (event) |
| Event | The event is that the message template is sent |
| MsgID | Message ID |
| Status | Sending status (failed due to other reasons than user's rejection) |