Meta Business/Cloud API发送WhatsApp交互式商品卡片时提示无效catalog_id

核心排查与解决步骤 #

1. 校验catalog_id格式准确性 #

• 确保传入的catalog_id是纯数字字符串，不要包含任何前缀（如fb_catalog_）或多余字符。直接复制「获取所有目录」接口返回的id字段值，避免手动输入或复制时引入无关内容。

2. 确认目录与WhatsApp业务账号的绑定关系 #

• 即使系统用户能访问目录，也需要该目录已绑定到你的WhatsApp Business Account（WABA）：
  • 进入Facebook商务管理平台，找到对应WABA的「目录关联」设置，检查目标目录是否已添加。
  • 未关联的话手动添加，等待5-10分钟系统同步后重试请求。

3. 验证访问令牌的权限覆盖 #

• 确认永久访问令牌包含以下必要权限：
  • whatsapp_business_messaging
  • catalog_management
  • business_management
• 通过Facebook访问令牌调试工具核对权限完整性，缺失则重新生成令牌并勾选对应权限。

4. 核对商品卡片请求的参数结构 #

• 确保catalog_id的嵌套层级符合要求，参考标准请求格式：

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<手机号>",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "product": {
      "catalog_id": "<你的目录ID>",
      "product_retailer_id": "<商品ID>"
    }
  }
}

• 避免将catalog_id放在错误的层级中，比如误置于interactive根节点下。

5. 检查目录与商品状态 #

• 确认目录处于「活跃」状态，无限制或停用标记。
• 待发送商品需在目录中处于「可售」状态，无地区限制、库存为0等异常情况——这类隐性问题也可能触发目录ID验证失败。

内容的提问来源于stack exchange，提问作者PRAKHAR KAUSHIK