使用HookDeck对接WhatsApp Cloud API时读取嵌套JSON的value字段报错

问题根源 #

你遇到的TypeError: Cannot read properties of undefined (reading 'value')，本质是代码尝试访问的嵌套字段不存在或未正确定位——哪怕截图里能看到changes有value，实际接收的payload结构可能和你预期的有差异，或者没处理数组/空值的情况。

具体解决步骤 #

• 先打印完整Payload确认结构
  不管用什么后端框架，先把接收到的完整请求体打出来，确认实际的嵌套层级：

  // 以Node.js Express为例
  console.log('完整Payload:', JSON.stringify(req.body, null, 2));
  

  注意WhatsApp官方的Webhook Payload结构是多层数组嵌套：entry是数组，每个entry里的changes也是数组，正确的value路径应该是entry[0].changes[0].value，而不是直接changes.value。另外要检查HookDeck是否对Payload做了包装（比如把原始数据放在event.payload这类字段里）。

• 用安全访问方式读取嵌套字段
  不要直接硬访问嵌套字段，用可选链操作符?.避免空值报错，同时处理数组索引：

  // 安全获取value
  const value = req.body.entry?.[0]?.changes?.[0]?.value;
  
  if (!value) {
    console.log('未找到有效的value字段');
    return res.sendStatus(200); // WhatsApp要求webhook返回200确认接收
  }
  
  // 后续处理value中的内容，比如消息、联系人等
  const message = value.messages?.[0];
  

• 检查HookDeck转发设置
  进入HookDeck的控制台，查看你的webhook端点的转发配置，确认是否开启了Payload转换、过滤等功能，这些设置可能会修改原始的WhatsApp Payload结构，导致你找不到目标字段。

额外提醒 #

WhatsApp Cloud API的Webhook Payload里，entry和changes都是数组，因为可能同时推送多个变更事件，所以必须通过索引（比如[0]）获取第一个元素，或者循环处理所有元素（如果需要批量处理）。

内容的提问来源于stack exchange，提问作者Romario Rio