微信模板消息传json如何传

微信模板消息传JSON：完整指南与最佳实践

在微信生态中，模板消息曾是开发者向用户触达服务通知的重要工具（注：当前微信模板消息能力已逐步迁移至“订阅消息”，但核心数据传递逻辑相似），无论是订单状态变更、服务提醒还是活动通知，消息内容的结构化传递都离不开JSON，本文将详细拆解微信模板消息中JSON数据的传递逻辑、格式规范、代码实现及常见问题,助你高效完成消息推送。

微信模板消息JSON数据的核心作用

微信模板消息的本质是“预定义格式+动态数据填充”，其中JSON承担了“动态数据”的载体角色，开发者需按照微信规定的模板结构，将变量值（如订单号、金额、时间等）封装成JSON对象，微信服务器解析后会将这些数据填入模板的对应位置,最终生成完整消息推送给用户。

JSON就像是“翻译官”，将你的业务数据转换成微信能读懂的“语言”。

JSON数据的基本格式与规范

微信模板消息的JSON数据需严格遵循以下规范,否则会导致消息发送失败或数据解析错误：

根节点为data，键值对对应模板变量

JSON的根节点必须是一个名为data的对象，其中的每个key对应模板中定义的变量名（如thing1、amount2等），value是对应的变量值。

示例： 为：“您有新的订单{{thing1}}，金额{{amount2}}元，请于{{date3}}前处理”，对应的JSON需为：

{
  "data": {
    "thing1": "奶茶订单",
    "amount2": "35.5",
    "date3": "2023-10-01 18:00"
  }
}

变量值类型与限制

• 类型：value必须是字符串类型（即使数字、布尔值也需转为字符串）。
• 长度：单个value长度不超过2048字节（约1024个汉字），整个data对象大小不超过40KB。
• 特殊字符：需转义JSON中的特殊字符（如双引号转义为\"，反斜杠\转义为\\），否则会导致JSON解析失败。

模板变量与JSON的映射关系

模板中的变量需提前在微信公众平台配置（如“模板库”选择模板或“自定义模板”创建），变量名格式通常为{{类型.序号}}（如{{thing1}}、{{date3}}），JSON中的key需去掉和类型前缀，仅保留序号（如thing1、date3）。

不同场景下的JSON传递实现

场景1：后端服务直接调用微信API（以Python为例）

使用微信提供的“服务通知”接口（需获取access_token），通过POST请求发送JSON数据。

关键步骤：

1. 获取access_token（通过AppID+AppSecret）。
2. 构造请求数据，包含touser（用户openid）、template_id（模板ID）、data（JSON数据）。

代码示例：

import requests
import json
def send_template_message(access_token, openid, template_id, data):
    url = f"https://api.weixin.qq.com/cgi-bin/message/template/send?access_token={access_token}"
    payload = {
        "touser": openid,
        "template_id": template_id,
        "data": data
    }
    headers = {"Content-Type": "application/json"}
    response = requests.post(url, json=payload, headers=headers)
    return response.json()
# 调用示例
access_token = "YOUR_ACCESS_TOKEN"
openid = "USER_OPENID"
template_id = "YOUR_TEMPLATE_ID"
data = {
    "thing1": "商品发货通知",
    "name2": "张三",
    "date3": "2023-10-01 15:30",
    "thing4": "顺丰速运",
    "number5": "SF1234567890"
}
result = send_template_message(access_token, openid, template_id, data)
print(result)

场景2：小程序/公众号前端触发消息（需用户授权）

若需在前端（如小程序）触发模板消息，需通过wx.requestSubscribeMessage获取用户订阅权限，后端再根据返回的template_id和用户数据发送JSON消息。

前端授权示例（小程序）：

// 请求订阅消息权限
wx.requestSubscribeMessage({
  tmplIds: ['YOUR_TEMPLATE_ID'],
  success: (res) => {
    if (res['YOUR_TEMPLATE_ID'] === 'accept') {
      // 用户授权成功，将token和openid传给后端
      sendToBackend(res['YOUR_TEMPLATE_ID']);
    }
  }
});

场景3：企业微信/第三方平台传递JSON

企业微信的“应用消息”或第三方平台（如商城SaaS）推送消息时，JSON格式与公众号模板消息类似，但需替换为企业微信的API地址（如https://qyapi.weixin.qq.com/cgi-bin/message/send），并使用corpid和corpsecret获取access_token。

常见问题与解决方案

JSON格式错误：invalid json

原因：JSON语法不正确（如缺少引号、逗号，或特殊字符未转义）。
解决：使用在线JSON格式化工具（如JSONLint）检查，确保data为根对象，key和value均为字符串，且符合JSON语法规范。

变量名不匹配：invalid template_id

原因：JSON中的key与模板变量名不一致（如模板用{{amount2}}，JSON中写成amount3）。
解决：登录微信公众平台查看模板详情，复制准确的变量名（去掉），确保与JSON的key完全一致。

变量值长度超限：value too long

原因：value超过2048字节或微信模板字数限制。
解决：截断或精简内容（如长文本用“...”省略），或联系微信申请调整模板字数限制。

用户未订阅：user refuse to receive

原因：用户未订阅该模板消息（仅订阅消息场景）。
解决：优化订阅引导话术，明确告知用户消息价值（如“订阅后可实时查看订单状态”），或通过服务通知触发用户订阅。

最佳实践

1. 提前校验数据：发送前用正则表达式校验JSON格式（如检查data是否存在、key是否合法），减少无效请求。
2. 使用模板变量复用：设计通用模板（如“订单通知”“活动提醒”），通过JSON填充不同数据，减少模板数量。
3. 错误日志记录：记录消息发送失败的响应码（如40003：touser字段为空），便于排查问题。
4. 测试环境先行：通过微信的“测试模板”功能验证JSON数据填充效果，避免直接推送生产环境数据。

微信模板消息传递JSON的核心是“规范格式+严格映射”，开发者需牢记data根节点、变量名匹配、字符串类型等关键要求，结合业务场景选择合适的调用方式（后端直接调用/前端触发授权），并通过错误排查和最佳实践优化消息推送的准确性和用户体验，随着微信订阅消息的普及,JSON数据传递的逻辑将长期是开发者触达用户的重要基础技能。