在 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 类型错误。

openclaw-whatsapp-gif

在WhatsApp聊天中获取并发送相关反应GIF，使用安全过滤器和确定性排序。用于用户请求GIF/表情包/反应时。

下载