# Send template messages

Debugging Tools

Interface should be called on the server side, not in the front end (Weixin Mini Program, web pages, APP, etc.) directly called, specific reference interface call guide

Interface name: sendTemplateMessage

This interface is used to send template messages to the user

# 1. How to call

# HTTPS calls

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

# Cloud Calls

  • Call method: officialAccount.messageTemplate.send

  • The input and exit parameters are the same as the HTTPS call, which can be called in the cloud call documentation

# Third party invocation

  • This interface supports Third Party Platform generation business call.

  • This interface belongs to the permission set id: 7,100-101

  • When a service provider is authorized by one of the permissions set, it can call on behalf of the merchant by using authorizer_access_token , which can be viewed in the third-party call documentation.

# 2. Request parameters

# Query parametersQuery String parameters

Parameter NametypeRequired to fill inExampleIntroductions
access_tokenstringyesACCESS_TOKENInterface invocation credentials, using access_token , authorizer_access_token

# Request BodyRequest Payload

Parameter NametypeRequired to fill inIntroductions
touserstringyesReceiver (user) openid
template_idstringyesRequired subscription template id
urlstringnoTemplate jump link (overseas account has no jump ability, url and miniprogram at the same time do not fill, no jump, url and miniprogram at the same time fill, priority jump Weixin Mini Program)
miniprogramobjectnoJump Weixin Mini Program fill in (url and miniprogram at the same time do not fill in, no jump, page and miniprogram at the same time fill in, priority jump Mini Program)
dataobjectyesThe content of the template must be given in accordance with the format given by the template (see note), in a format such as {"key1": { "value": any }, "key2": { "value": any } }
client_msg_idstringnoAnti-reentry id. For the same openid + client_msg_id, send only one message, valid for 10 minutes, more than 10 minutes is not guaranteed. If there is no recourse requirement, you may not fill it

# Body.miniprogramObject Payload

Jump Weixin Mini Program fill in (url and miniprogram at the same time do not fill in, no jump, page and miniprogram at the same time fill in, priority jump Mini Program)

Parameter NametypeRequired to fill inIntroductions
appidstringno Weixin Mini Program AppID
pagepathstringnoWeixin Mini Program Jump path

# Body.dataObject Payload

The content of the template must be given in accordance with the format given by the template (see note), in a format such as {"key1": { "value": any }, "key2": { "value": any } }

Parameter NametypeRequired to fill inIntroductions
thing.DATAstringnoThings can be combined with Chinese characters, numbers, letters or symbols, within 20 characters

Scope of application: For the selection of name keywords, address keywords, institution / organization name keywords (e.g., unit name, bank name, hospital name, department, class), product name keywords keywords (eg., drug name, stock name, course name, subject name, job name)

character_string.DATAstringnoCharacter string, which can be a combination of numbers, letters, or symbols up to 32 bits

Scope of application: For digital / coding / number / order number / card number / flight number keyword (e.g. securities codes, equipment numbers, order number, bank card number, web address)

time.DATAstringnoTime, 24-hour time format (supported + year and day), support for HH: MM: SS or HH:MM, support for filling time periods, connect between two time points with a "~" symbol, for example: "15:01" or "15:01 October 1, 2019"

Scope of application: for choice of time category keywords

amount.DATAstringnoAmount, 1 currency sign + no more than 10 pure digits, can be mixed decimal, the end can be "yuan"

Scope of application: for choice of keywords in currency category

phone_number.DATAstringnoPhone number, within 17 numbers, numerals, symbols, Example: + 866-0766-66888866

Scope of application: For keyword selection in telephone numbers

car_number.DATAstringnoLicense plate number, less than 8 digits, the first and last digits can be Chinese characters, the rest are letters or numbers, such as: Guangdong A8Z888

Scope of application: keywords for license plate numbers

const.DATAstringnoConstants, within 20 characters, more than cannot be forwarded; Only the character strings and empty strings approved by the audit can be issued.

Scope of application: availability / mode / type / reminder / explaination / details Keyword selection (e.g. payment status, queuing status, weather status, logistics status, medication reminder, repayment reminder)

# 3. Return Parameters

# Response Payload

Parameter NametypeIntroductions
msgidnumberMessage id
errcodenumberError code
errmsgstringError Description

# 4. Note

URL and miniprogram are not required fields, if not pass the template without jump;If both passes, it will be redirected to Weixin Mini Program. Developers can choose one of these transitions based on their actual needs.When the user's WeChat Guest version does not support the jump Mini Program, it will jump to the url.

All data points:

  • Symbols: Represents common symbols other than Chinese, English, and numbers, and cannot carry control characters such as changing lines.
  • Time: format supports HH: MM: SS or HH: MM.
  • Dates: Contain the date of the year, in the format of y m m d day, y m month, m m d date, or be connected with '-', '/',.' symbols, such as 2018-01-01, 2018 / 01 / 01, 2018.01.01, 2018-01, 01-01.

Each template parameter is prefixed with a type, for example, the first numeric template parameter is number01.DATA, The second is number02.DATA. When sending a template notification, the content of the notification should be consistent with the template parameters. Each template parameter is prefixed by type. For example, the first digital template parameter is number01.DATA and the second is number2.DATA

For example, the content of the template is

姓名: {{name01.DATA}}
金额: {{amount01.DATA}}
行程: {{thing01.DATA}}
日期: {{date01.DATA}}

The corresponding json is

{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "data": {
      "name01": {
          "value": "某某"
      },
      "amount01": {
          "value": "¥100"
      },
      "thing01": {
          "value": "广州至北京"
      },
      "date01": {
          "value": "2018-01-01"
      }
  }
}

If the parameter does not meet the requirements, you are prompted as follows, indicating the field that does not:

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

# 5. Code examples

Example Requests

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

Return an example

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

# 6. Error code

The following is a list of error codes for this interface, other error codes can refer to General error codes

Error codeError DescriptionSolutions
-1system errorThe system is busy, so the developer is asked to try again in a few minutes.
40001invalid credential  access_token isinvalid or not latestAppSecret error while getting access_token, or access_token is invalid.Developers should check that AppSecret is correct, or that they are calling interfaces for the appropriate Official Account
40003invalid openidInvalid OpenID. Please confirm if the OpenID is following Official Account, or if it is another OpenID from the Official Account message template.
40008invalid message typeUnlawful Message Types
40013invalid appidInvalid AppID, please check the correctness of the AppID, avoid abnormal characters, pay attention to the case
40036invalid template_id sizeInvalid template_id length
40037invalid template_idInvalid template_id
40039invalid url sizeIllegal URL length
40249Sending marketing content is prohibited
43116The template is restricted from being published
47003Parameter format error

# 7. Scope of application

This interface supports "Service Account (authentication only)" account type calls.None of the other account types can be invoked without special instructions.