WeChat Open Platform

Mini Programs Documentation

Templated Messages

Based on WeChat's notification channels, we have provided developers with templated message capabilities that can reach users effectively, so that they can achieve a closed-loop service and provide a better experience.

Template push location: Service Notification

Conditions for sending templates: The user triggers this themselves after interacting with a page in the WeChat system. Refer to Instructions on Conditions for Sending.

Template redirection capability: You can only redirect to various pages for the account sending the template when clicking to view details.

Directions for use

  1. Get template id

Log in to https://mp.weixin.qq.com to get templates. If there are no suitable templates, you can request that new templates are added and use these after they have passed review. Refer to Template Review Instructions for further details.

  1. When the page's <form/> component and attribute report-submit are true, it can be declared that a templated message needs to be sent. The formId, which is used to send templated messages, can now be obtained by clicking on the button to submit the form. Or, when a user completes a payment action, they can get a prepay_id that is used to send templated messages.

  2. Call interface to send templated messages (refer to Interface Instructions for further details)

Interface Instructions

1. Get access_token

An access_token is a unique global interface call credential. Developers need to use an access_token when calling various interfaces and are requested to save them appropriately. An access_token's storage needs to be able to retain a minimum of 512 characters. The validity period of an access_token is currently two hours. They need to be refreshed regularly. Getting a duplicate will cause the previously obtained access_token to become invalid.

Instructions on usage and generation methods for access_tokens required for Open Platform API calls:

  1. In order to keep AppSecret confidential, third parties need a central server for obtaining and refreshing access_tokens. All access_tokens used by other business logic servers come from this central server. The business logic servers should not refresh by themselves, otherwise this may cause access_token coverage to affect business.
  2. The current access_token validity period is transmitted through the expires_in that is returned. It is currently a value within 7,200 seconds. The central server needs to refresh a new access_token in advance according to this validity period. During the refresh process, the central server's external output is still the old access_token, the Open Platform backend will now guarantee that both new and old access_tokens are available within the short refresh time. This ensures a smooth transition for third party business.
  3. The access_token validity period may be adjusted in future, so the central server's internal timer not only needs to refresh automatically, it also needs to provide a passively refreshing access_token interface. This makes it easy for business servers to be able to trigger the access_token refresh process in situations where an API call learns that the access_token has timed out.

Developers can use their AppID and AppSecret to call this interface to get an access_token. The AppID and AppSecret can log in to the official WeChat Official Account Platform website - Settings - Development Settings to get an access_token (need to be bound as a developer and account needs to not have any unexpected statuses). Please save AppSecrets yourself after they are generated, because they are reset every time they are generated and viewed on the Open Platform. Note that the https protocol needs to be used when calling any WeChat interface. If a third party does not use a central server, and selects various business logic points to refresh access_tokens on its own instead, this may cause a conflict and lead to service instability.

Interface address:

https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

HTTP request methods:

GET

Parameter descriptions:

Parameter Required Description
grant_type Yes Gets access_token and enters client_credential
appid Yes Third party user's unique credential
secret Yes Third party user's unique credential key, i.e. AppSecret

Return parameter descriptions:

Under normal circumstances, WeChat will return the following JSON packets to the developer:

{"access_token": "ACCESS_TOKEN", "expires_in": 7200}
Parameter Description
access_token Credential obtained
expires_in Credential validity period, unit: seconds

When errors occur, WeChat will return information including the error code. A JSON packet example is given below (this example is an invalid AppID error):

{"errcode": 40013, "errmsg": "invalid appid"}

2. Send templated messages

Interface address: (ACCESS_TOKEN needs to be converted into the access_token obtained as above).

https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN

HTTP request methods:

POST

POST parameter descriptions:

Parameter Required Description
touser Yes Recipient (user)'s openid
template_id Yes id for templated message that needs to be sent
page No The redirection page after clicking on the template card, limited to a page within the Mini Program. Supports parameters (example index?foo=bar). The template will not redirect if this field is not filled in.
form_id Yes In a form submission scenario, this is the formId brought by a submit event; in a payment scenario, this is the prepay_id for this payment
data Yes Template content, an empty template will be sent if this is not filled in
color No Color of text within template, default is black if this is not filled in
emphasis_keyword No Template requires emphasis keywords, default is no enlargement if this is not filled in

#####Example:

{
  "touser": "OPENID",  
  "template_id": "TEMPLATE_ID", 
  "page": "index",          
  "form_id": "FORMID",         
  "data": {
      "keyword1": {
          "value": "339208499", 
          "color": "#173177"
      }, 
      "keyword2": {
          "value": "January 5, 2015 12:30", 
          "color": "#173177"
      }, 
      "keyword3": {
          "value": "Sheraton Guangzhou Hotel", 
          "color": "#173177"
      } , 
      "keyword4": {
          "value": "208 Tianhe Road, Tianhe District, Guangzhou", 
          "color": "#173177"
      } 
  },
  "emphasis_keyword": "keyword1.DATA" 
}

Return code descriptions:

A JSON packet will be returned after the templated message interface is called.

Example of the JSON packet that is normally returned:

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

Error code information will be returned when errors occur, the descriptions are as follows:

Return code Description
40037 template_id incorrect
41028 form_id incorrect or expired
41029 form_id already used
41030 page incorrect
45009 Interface calls exceeded limit (current default daily call limit is 1 million per account)

Usage results:

Instructions on conditions for sending

  1. Payment

    When a user has completed a payment action in a Mini Program, the developer is permitted to push a limited number of templated messages to the user within seven days (one message can be sent for each payment, the number of messages sent for several payments is independent, they do not affect each other).

  2. Submission of forms

    When a user submits a form in a Mini Program and this form declares that a templated message must be sent, and the developer needs to provide the user with a service, the developer is permitted to push a limited number of templated messages to the user within seven days (one message can be sent for each form submitted, the number of messages sent for several submissions is independent, they do not affect each other).

Review instructions

1.Subjects

1.1 Subjects cannot be the same.

1.2 Subject meanings cannot be overly similar.

1.3 Subjects must end in "reminder" or "notice".

1.4 Subjects cannot include non-general industry content, such as special symbols or personalized phrases.

1.5 Subjects must be able to reflect specific service scenarios.

1.6 Subjects must not involve marketing-related content, including but not limited to:

Marketing-oriented notices about consumer discounts, shopping rebates, product updates, discount coupons, vouchers, red packets, member cards, bonus points, or events.

2.Keywords

2.1 The same keywords cannot exist under the same subject.

2.2 Keywords under the same subject cannot be overly similar.

2.3 Keywords cannot include non-general industry content, such as special symbols or personalized phrases.

2.4 Keyword content examples must match keywords.

2.5 Keyword meanings cannot be too broad, they need to be limited. For example: "content" is too broad in meaning, it would not pass review.

Noncompliance instructions

In addition to not violating the operating specifications, the following rules must not be violated, including but not limited to:

  1. Maliciously inducing a user to perform a trigger action, to achieve the objective of sending the user a template, is not permitted.
  2. Malicious harassment, that is, the sending of templates that harass a user, is not permitted.
  3. Malicious marketing, that is, sending templates for marketing purposes, is not permitted.
  4. Using a service account to send templates informing a user about the service-related content triggered within a Mini Program is not permitted.

Penalty instructions

The degree of punishment corresponds to the circumstances of the violation. The general penalty rules are as follows:

For the first violation, the noncompliant template is deleted as a warning.

For the second violation, the interface is blocked for 7 days.

For the third violation, the interface is blocked for 30 days.

For the fourth violation, the interface is blocked permanently.

A message will be sent informing of the penalty outcome and reason.

Bugs & Tips
  1. tip: WeChat versions 6.5.2 and above support template functions. Earlier versions will be unable to receive templated messages.