在 WhatsApp 模板中通过 Flow 按钮传递参数时，必须将自定义字段（如 to_number）严格嵌套在 payload.data 对象内，且值需为字符串类型；否则 Flow 端会因 schema 校验失败而返回 payload-schema-error。
在 whatsapp 模板中通过 flow 按钮传递参数时，必须将自定义字段（如 `to_number`）严格嵌套在 `payload.data` 对象内，且值需为字符串类型；否则 flow 端会因 schema 校验失败而返回 `payload-schema-error`。
要使 WhatsApp Flow 正确接收并解析模板按钮中的参数，关键在于 Payload 结构合规性 和 数据类型显式声明。WhatsApp 官方 Flow API 要求所有自定义参数必须位于 payload 字符串内嵌套的 data 对象中，且该对象下的字段值必须为标准 JSON 基础类型（如字符串、数字、布尔值），不可为 None、整数未转义或嵌套结构错误。
✅ 正确的参数格式（Python 示例）
import json
payload = {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": to_number, # 目标手机号（纯数字字符串，如 "27815492711"）
"type": "template",
"template": {
"name": "your_template_name",
"language": {"code": "en"},
"components": [
# header（可选）
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {"link": "https://example.com/image.jpg"}
}
]
},
# flow button（核心：参数必须在此处注入）
{
"type": "button",
"sub_type": "flow",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": json.dumps({
"action": "INIT",
"data": { # ← 必须存在且为 dict 类型
"to_number": str(to_number) # ← 强制转为字符串，避免 int 导致校验失败
}
})
}
]
}
]
}
}⚠️ 常见错误与修复说明
- ❌ 错误写法：
"payload": json.dumps({"action": "INIT", "to_number": 27815492711})
→ 缺失data包裹层，且to_number为整数（非 JSON string），Flow 端无法匹配 schema。 - ❌ 错误写法：
"payload": json.dumps({"action": "INIT", "data": {"to_number": None}})
→None会被序列化为null，Flow 不接受null值作为 required 字段。 - ✅ 正确原则：
- 所有业务参数必须置于
"data": {...}内； - 字符串类字段（如手机号、用户 ID）务必调用
str()显式转换； - 避免传递空值、字典/列表等复杂类型（除非 Flow Schema 明确支持）；
- 使用
json.dumps()序列化前，建议先用jsonschema或日志校验结构合法性。
- 所有业务参数必须置于
? Flow 端安全取值方式（推荐）
elif action == "INIT":
try:
# 安全获取：data 是 Flow 自动解析后的 dict，无需再解码
flow_data = data.get("data", {})
user_number = flow_data.get("to_number", "").strip()
if not user_number or not user_number.isdigit():
raise ValueError(f"Invalid to_number format: {user_number}")
# 后续逻辑...
response_dict = {
"screen": "DETAILS",
"data": {"to_number": user_number} # 保持字符串一致性
}
except Exception as e:
logger.error(f"INIT handler failed: {e}")
return https_fn.Response(
json.dumps({"error": "invalid_payload"}),
status=400,
mimetype="application/json"
)遵循以上规范，即可确保 WhatsApp 模板按钮触发 Flow 时，参数能被稳定、准确地传递与消费，彻底规避 payload-schema-error 类型错误。
