Facebook Messenger聊天插件未触发messaging_referrals Webhook事件

我来帮你一步步排查这个问题，之前我也遇到过类似的情况，几个关键点很容易忽略：

1. 先确认ref参数的触发时机和格式 #

首先要明确：messaging_referrals事件只会在用户首次点击聊天插件发起对话时触发，如果用户之前已经和你的页面打过招呼，后续打开聊天框不会重复触发。测试的时候一定要用浏览器隐私模式，或者清除Facebook相关Cookie后重试，避免会话缓存的影响。

另外，你代码里的ref="OPTIONAL_WEBHOOK_PARAM"要注意：

• 必须是URL安全的字符串，不能包含空格、中文或未转义的特殊字符，动态生成的话记得用encodeURIComponent()处理
• 如果是从Cookie取追踪值，要确保渲染.fb-customerchat元素前，Cookie已经能被正确读取（后面会说动态设置的方法）

2. 检查Webhook的订阅配置是否到位 #

你说已经加了messaging_referrals事件，但要确认几个细节：

• 你的Webhook是绑定到Facebook Page的，不是应用本身的事件（Chat Plugin属于页面功能）
• 在Webhook的订阅字段里，除了messaging_referrals，还要确保勾选了messaging大类权限
• 你的应用必须拥有该页面的管理员/编辑权限，否则无法接收页面事件

可以直接在开发者后台的Webhook设置里，点击「测试」按钮手动发送messaging_referrals事件，如果能收到，说明Webhook本身没问题，问题出在前端触发逻辑。

3. 确保Chat Plugin的SDK初始化正确 #

页面必须正确加载Facebook的SDK，而且版本要尽量新（比如v18.0+），旧版本可能存在参数传递的bug。完整的初始化代码应该是这样的：

<script>
  window.fbAsyncInit = function() {
    FB.init({
      xfbml            : true,
      version          : 'v18.0'
    });
  };

  (function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s); js.id = id;
    js.src = 'https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js';
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'facebook-jssdk'));
</script>

还要注意你的page_id="ABC"必须替换成实际的数字ID，不能是自定义用户名。

4. 动态设置ref参数（从Cookie取值的正确姿势） #

如果你的ref是从Cookie取追踪值，不能直接写死在HTML里，要在页面加载后动态设置，确保SDK初始化前能拿到最新值。比如用这段代码：

// 封装读取Cookie的方法
function getCookie(name) {
  let matches = document.cookie.match(new RegExp(
    "(?:^|; )" + name.replace(/([\.$?*|{}\(\)\[\]\\\/\+^])/g, '\\$1') + "=([^;]*)"
  ));
  return matches ? decodeURIComponent(matches[1]) : undefined;
}

// 页面加载完成后设置ref属性
document.addEventListener('DOMContentLoaded', function() {
  const chatElement = document.querySelector('.fb-customerchat');
  if (chatElement) {
    const trackingId = getCookie('你的Cookie名称');
    if (trackingId) {
      chatElement.setAttribute('ref', trackingId);
    }
  }
});

这段代码要放在SDK加载脚本之前，保证SDK初始化时能读到正确的ref值。

5. 排查Facebook的事件限制 #

最后还有几个容易踩的坑：

• 如果用户已经在Messenger客户端和你的页面聊过，切换到网站插件不会触发新的referral事件
• 同一个浏览器多次测试会触发Facebook的会话缓存，导致事件不触发，一定要用隐私窗口测试
• 可以去开发者后台的「事件管理器」查看页面的事件日志，看看messaging_referrals是否被触发但没传递到Webhook，有没有错误提示

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