Node.js开发Messenger机器人Quick reply不生效问题求解

核心代码bug修复 #

你当前代码存在致命的Promise逻辑错误：在调用request发起Graph API请求后，立刻在外层执行了resolve()，没有等待API请求完成就结束了当前异步流程。纯文本消息体积极小，大概率在连接被回收前就完成了发送，因此可以正常送达；带quick_replies的结构化消息体积更大，请求未发送完成连接就被释放，直接导致消息丢失，且你的服务端不会捕获到任何报错。
修复后的可运行代码如下：

return new Promise((resolve, reject) => {
  const request_body = {
    "recipient": {
      "id": sender_psid
    },
    "messaging_type": "RESPONSE",
    "message": {
      "text": "Pick a color:",
      "quick_replies": [
        {
          "content_type": "text",
          "title": "Red",
          "payload": "POSTBACK_PAYLOAD_1"
        },
        {
          "content_type": "text",
          "title": "Green",
          "payload": "POSTBACK_PAYLOAD_2"
        }
      ]
    }
  }
  request({
    "uri": `https://graph.facebook.com/v14.0/me/messages?access_token=${PAGE_ACCESS_TOKEN}`,
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    // 必须在请求回调内处理成功/失败逻辑，不要提前resolve
    if (err) {
      console.error('请求连接错误:', err)
      reject(err);
      return
    }
    // 必须打印API返回的body，很多业务错误不会触发request的err
    if (body.error) {
      console.error('Meta API返回业务错误:', body.error)
      reject(body.error)
      return
    }
    resolve("done");
  });
})

其他高频不生效原因排查 #

• 应用模式与测试权限问题：如果你的应用处于开发模式，所有接收消息的用户必须提前添加到应用后台的测试人员/测试角色列表中，非测试用户只能收到纯文本消息，所有结构化消息（快速回复、按钮、模板、卡片）都会被Meta侧静默丢弃，不会返回报错。
• 快速回复格式硬限制校验：
  • 单个文本类型快速回复的title字段长度不能超过20字符，payload字段长度不能超过1000字符
  • 单条消息附带的quick_replies数组最多支持13个选项，超出后整条消息发送失败
  • quick_replies字段不能和message.attachment（附件、模板）字段同时存在，混发会直接触发消息格式错误
• 权限校验：确认使用的PAGE_ACCESS_TOKEN为当前关联主页的有效长期令牌，且已授予pages_messaging权限，令牌过期、权限缺失时结构化消息会被拦截，纯文本消息在部分场景下仍可正常发送。
• Webhook配置无需额外增加订阅项，你当前开启的messages、messaging_postbacks订阅已经完全满足快速回复的发送、回调接收需求。

注：修复代码后建议先在测试账号（已加入测试人员列表）中验证，发送消息时同步打印Graph API返回的响应体，所有格式、权限类错误都会在响应体的error字段中明确标注错误码与原因。

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