Templated Messages
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

A templated message may be used by official accounts to automatically send important service notices to users. It can be used in various scenarios such as a notification when the user has used a credit card for a purchase or when a product purchase has been successfully completed. Templated message should never be used to send promotional messages (e.g. ads) or unsolicited messages.For rules for using templated messages, refer to Templated Messages Operation Specification.

Usage instructions:

1. Service accounts may apply for access to the templates messages feature  by going to "Function" -> "Add" on the WeChat Official Accounts Admin Platform; however, only service accounts granted access are permitted use this feature.
2. When applying, the “industry” field is a required field. Two fields must be selected and which subsequently be modified a maximum of once per month.
3. Only templates previously configured in the library corresponding to the selected fields selected may be used.
4. Official accounts may activate a maximum of 15 templates may be activated at any one time.
5. At the current time, a template may be used up to 100,000 times per day. Note: the calling limit was increased on November 18, 2014, from 10,000 to 100,000 times per day; the limit may be queried in the developer center after logging into the WeChat Official Accounts Admin Platform.

Notes on using templates:

1. Before a template is used, template ID and parameters must be set first.
2. Parameters names must end with ".DATA"; otherwise, they will be regarded as reserved words.
3. The symbol "{{ }}" is reserved by the system.

Contents

Setting Industry IDs

Setting an official account's industry IDs can be completed in on the WeChat Official Accounts Admin Platform and may be changed up to once per month. Only templates corresponding to the selected industries may be used. As a convenience to developers, an official account's industry IDs may be changed via an API call.

Request Description

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

POST Data

Example:

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

Parameter Description

Parameter Required Description
industry_id1 Yes First selected ID industry ID
industry_id2 Yes Second selected industry ID

Industry Type IDs

Industry Main Type Industry Sub-Type ID
Information Technology Internet/E-commerce 1
Information Technology IT Software and Services 2
Information Technology IT Hardware and Accessories 3
Information Technology Electronics 4
Information Technology Telecom Operators 5
Information Technology Online Games 6
Finance Banking 7
Finance Investment Funds/Wealth Management 8
Finance Insurance 9
Food & Beverage Food & Beverage 10
Hospitality & Tourism Hotel 11
Hospitality & Tourism Travel 12
Transportation and Warehousing Express Delivery 13
Transportation and Warehousing Logistics 14
Transportation and Warehousing Storage 15
Education Training 16
Education School 17
Government and Public Sector Academic Research 18
Government and Public Sector Traffic Police 19
Government and Public Sector Museum 20
Government and Public Sector Utilities/Non-profit Organization 21
Medicine & Nursing Pharmaceutical & Healthcare 22
Medicine & Nursing Beauty Care 23
Medicine & Nursing Health & Hygiene 24
Transportation Automobile 25
Transportation Motorcycle 26
Transportation Train 27
Transportation Airplane 28
Real Estate Construction 29
Real Estate Property 30
Consumer Goods Consumer Goods 31
Business Service Legal 32
Business Service Exhibition Services 33
Business Service Intermediary Services 34
Business Service Certification 35
Business Service Audit 36
Sports and entertainment Media 37
Sports and entertainment Sports 38
Sports and entertainment Entertainment 39
Print Print 40
Others Others 41

Obtaining Template ID

Obtaining a template ID may be completed on the WeChat Official Accounts Admin Platform. =As a convenience to developers, the template ID can also be obtained via the API.

Request Description

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

POST Data

Example:

{
   "template_id_short":"TM00015"
}

Parameter Description

Parameter Required Description
template_id_short Yes ID of a template, in the form of "TM**", "OPENTMTM**", etc.

Return Description

An example of a successful JSON response is as follows:

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

Sending a Templated Message

Request Description

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

POST Data

Example:

{
   "touser":"OPENID",
   "template_id":"IDQ52-dMg3ZBsz1OIL13AruOXIEvpLFluKFxLHnLNZY",
   "url":"http://tmplmsg.wechat.com/cgi-bin/test",
   "topcolor":"#666",
   "data":{
           "first": {
               "value":"Information successfully changed.",
               "color":"#173177"
           },
           "keyword1":{
               "value":"Last 4 digits (9527)",
               "color":"#173177"
           },
           "keyword2": {
               "value":"October 27, 2014 18:36",
               "color":"#173177"
           },
           "remark":{
               "value":"If you didn't perform this action, change your security information as soon as possible.",
               "color":"#173177"
           }
    } 
}

Return Description

An example of a successful JSON response is as follows:

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

Display Result

Tmplmsg1.png

Event-based Message

After a templated message has been sent, the WeChat Official Account System will send notification of transmission to the addresses for servers listed by the developer on the WeChat Official Account Admin Platform.

1. The XML-based format for a notification of successful transmission is as follows:

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

Parameter Description

Parameter Description
ToUserName WeChat ID of the official account
FromUserName OpenID of the message receiver
CreateTime Creation time
MsgType Event type
Event Description of event that triggered the event-based message
MsgID Message ID
Status Sending status (successful)

2. The XML-based format for a notification of a rejected transmission caused by user rejection (the user has opted to reject messages from the official account) is as follows:

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

Parameter Description

Parameter Description
ToUserName WeChat ID of the official account
FromUserName OpenID of the message receiver
CreateTime Creation time
MsgType Event type
Event Description of event that triggered the event-based message
MsgID Message ID
Status Sending status (rejected)

3. The XML-based format for a notification of a failure transmission caused by other reasons is as follows:

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

Parameter Description

Parameter Description
ToUserName WeChat ID of the official account
FromUserName OpenID of the message receiver
CreateTime Creation time
MsgType Event type
Event Description of event that triggered the event-based message
MsgID Message ID
Status Sending status (failure other than rejection)


Templated Messages Operation Specification

Templated Messages allows Official Accounts to send service notifications. Using this API, developers can set parameters (starting with "{ {" and ending with ".DATA} }") in the template, assign values to these parameters when the template is called, and send the template. Only templates from the applicable industry set for the Official Account can only be selected from the template library. If a required template is currently unavailable in the template library, you may add a new template to the template library. Review the following requirements for new templates first before adding a new template. For details about how to use the API, refer to Templated Messages.

I. Supported Templated Messages

Templated messages cannot contain advertising or marketing not requested by the recipient.

1. Instant Response-type Message Template

This templated message type can be immediately sent after a WeChat user triggers a certain event or activity. The templated message will be instantly pushed to the user to notify the user with relevant content. Examples of this templated message type are as follows:

Profile change notification, municipal service instant notification, item (including virtual items) collection notification, transaction notification, attendance notification, status notification, login reminder notification and other instant notifications triggered by users.

2. Instant Notification-type Message Template

This templated message type can be pushed to users without being triggered when a major event important to the user happens. The frequency for pushing this templated message type is strictly controlled. Strong, punitive measures will be taken if messages that may harass users are frequently pushed. Examples of this templated message type are as follows:

2.1 Templated messages pushed monthly on a fixed date
Examples: Monthly bill notification, telephone bill notification, utility bill notification, property fee notification or other messages pushed to users on a monthly basis.
2.2 Templated messages pushed monthly on a non-fixed basis
Fault notification, alarm and warning notification, due date reminder notification, payment reminder notification, meeting reminder notification, event reminder notification, departure reminder notification, flight delay reminder notification and other messages important to users.

3. Non-instant Processed Message Template

Templated messages of this type are trigerred by certain event or activity by a WeChat user and sent after a brief delay. A certain period of time is first required in order to process the message content and delivery the relevant result in a reply to the user. Examples of this templated message type are as follows:

Review result notification, refund result notification, bidding result notification, order acceptance result notification, registration result notification, feedback notification and other delayed messages important to users.

II. Prohibited Templated Message Types

1. Message Templates Suspected of Advertising and Marketing

Templated messages of this type are sent for advertising and marketing purposes, and used to induce consumers. Strong punitive measures will be taken against these types templated messages when identified. The Official Account will have it’s API access disabled and, in egregious instances, the account may be banned. Examples of this prohibited templated message type are as follows:

Purchase benefits notification, rebate notification, reduced price notification, new stock arriving notification and other consumption-related marketing notifications.

2. Message Template Sent Too Frequently Which May Harass Users

Templated messages sent to frequently and which are unwanted by users can be annoying. Therefore, message sending frequency is closely monitored. Strong punitive measures will be taken against accounts pushing messages that harass users. The Official Account concerned will have its API access disabled and , in egregious instances, the account may be banned. Examples of prohibited messages are as follows:

Due date reminder notifications too frequently, payment reminder notifications too frequently, and other messages that may harass the users.

3. Auto-reply Message Template

This templated message type will auto reply to a message sent to the Official Account and is not allowed to be sent. Examples of this prohibited message type are as follows:

Query reply notifications and other automated messages are prohibited. Use the Auto-reply API instead.

4. Templated Messages Related to Lucky Money, Coupons, Gift Cards, Vouchers or Membership Cards

This templated message type is prohibited. Developers should use Coupons instead.

III. Template Review Standards

1. Templates must comply with all requirements for supported templated messages listed above.
2. Notification use case must be specific and timely, with the static text clearly describing the specific use case.
3. Template must be filled according to the guidelines provided below.
4. An existing template of similar use must not already exist in the template library in order to be approved.
5. Templates containing advertising, marketing or harassing content  will be rejected.

IV. Guidelines for Submitting a Template

Templated message must strictly abide by the following rules when submitting; otherwise, the template may be rejected.

1. Template body cannot exceed 200 Chinese characters, with at least 10 static characters or punctuation marks provided.
2. Within the template, values can be assigned to each of the parameters when sending. Parameters must start with "{ {" and end with ".DATA} }".
3. Content example is a copy of the template after example values are assigned to the parameters in the template content. Developers must carefully fill in the content example to help reviewers understand the template’s purpose.
4. Developer can insert a line feed "\n" to add a line break to a parameter. Therefore, it is recommended to write the parameter prior to the line break, and include "\n" to add a line break when required.
5. The first sentence in the template body should clearly describe the message’s purpose, and is described by the "{ {first.DATA} }" parameter. This part does not need to be modified when the title changes.
6. The body of the template must contain between two to five name-value pairs of "keyword name:keyword content value"  format (full-width colon separating the name and value), which ensures an optimum experience on the WeChat client.
7. The "{ {remark.DATA} }" parameter must be included at the end of the template body. By using this parameter, developers can add multiple lines of content as required. For example, in a template with two parameters (Name and Time), if three parameters (Name, Time and Location) are then required, you can add "Location" value to the "remark" parameter ("\n" can be used to add a line break when required). In this way, more keywords may be added by using the "remark" parameter, which makes the template more extensible.
8. Parameters directly connected to one another should be simplified to a single parameter. By assigning value to a single parameter instead of two, the template content is made less complex.
9. To make the template more universal, keywords such as brand names are not allowed in the template header and template body.
Developer Guide
Custom-defined Menu
WeChat JS-SDK