跳到主要内容

故障排除

遇到问题了？别担心——大多数问题都有简单的解决方法！在下面找到您的问题并按照解决方案操作。

Webhook 验证失败​

错误： "The callback URL or verify token couldn't be validated."

可能的原因和修复：​

#原因修复
1URL 不是 HTTPS在您的服务器上安装 SSL 证书
2回调 URL 中有拼写错误直接从模块设置中复制粘贴
3验证令牌中有拼写错误直接从模块设置中复制粘贴
4服务器阻止了请求检查您的防火墙/安全插件
5.htaccess 重定向问题确保 URL 不会重定向（没有 www ↔ 非 www 重定向问题）
6选择了 "User" 而不是 "Page"在 Facebook webhook 中将下拉菜单更改为 "Page"

如何调试：​

  1. 打开浏览器并直接访问您的 webhook URL： 
    https://yourcrm.com/facebookleadsintegration/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123
  2. 如果正常工作，您应该看到页面上显示 test123
  3. 如果看到错误页面，问题出在服务器端
提示

仍然不工作？ 检查您服务器的错误日志 /path/to/your/crm/application/logs/

Facebook 登录时出现 "Invalid Scopes" 错误​

错误： "Invalid Scopes: pages_manage_metadata"

修复：​

这意味着模块请求了一个已弃用的权限。确保您使用的是模块的 最新版本（v2.0.0+），它使用正确的权限：

  • pages_show_list
  • pages_read_engagement
  • leads_retrieval
  • pages_manage_ads
  • ads_management

将您的模块更新 到最新版本即可修复。

"Error Accessing App" / "App Not Active"​

错误： 尝试连接 Facebook 时，看到 "Error Accessing App" 或 "The app is not active."

可能的原因和修复：​

#原因修复
1模块设置中的 App ID 错误仔细检查 App ID 是否与您的 Meta App 匹配
2应用已被删除或禁用在 developers.facebook.com/apps 检查您的应用
3您不是应用的管理员/开发者在 App Roles → Roles 中添加自己
4应用限制检查 App Settings → Basic → App Restrictions

测试线索有效但真实线索未到达​

模块的 "Send Test Lead" 按钮有效，但来自 Facebook 的真实线索没有出现。

检查以下内容：​

#检查项如何检查
1您的主页已订阅吗？Settings → Connected Pages → 必须显示 "Monitoring"
2Webhook 已验证吗？Settings → Connection Status → Webhook 必须为绿色
3"leadgen" 已订阅吗？Meta App → Webhooks → Page → "leadgen" 必须被勾选
4广告使用的是正确的主页吗？Ads Manager → Ad Set → 确保使用的是已订阅的主页
5广告在运行吗？Ads Manager → 广告活动状态应为 "Active"

使用 Facebook 的工具测试：​

使用 Lead Ads Testing Tool 发送真实的 webhook 测试线索。如果这有效但实际广告不行，问题可能出在您的广告活动设置上。

模块页面出现 500 错误​

症状： 模块页面显示空白页或 "500 Internal Server Error"

修复：​

  1. 检查 PHP 错误日志：

    /path/to/your/crm/application/logs/log-YYYY-MM-DD.php

  2. 常见原因：

    • PHP 版本太旧（需要 7.4+）
    • 缺少 PHP 扩展（cURL、JSON）
    • 文件权限不正确
    • 上传过程中模块文件损坏

  3. 修复文件权限：

    find /path/to/modules/facebookleadsintegration -type f -exec chmod 644 {} \;
    find /path/to/modules/facebookleadsintegration -type d -exec chmod 755 {} \;

  4. 如果文件可能损坏，重新上传模块

复制按钮不工作​

症状： 点击 webhook URL 或验证令牌旁边的 "Copy" 按钮无反应。

修复：​

  • 确保您的 CRM 通过 HTTPS 访问——剪贴板 API 需要安全上下文
  • 尝试手动选择文本并按 Ctrl+C
  • 检查浏览器控制台是否有 JavaScript 错误（F12 → Console 标签）

线索卡在 "Pending Retry"​

症状： 同步历史显示状态为 "Pending" 的线索未被处理。

修复：​

  1. 手动处理： 前往 Sync History → 点击 "Process Retry Queue"
  2. 检查 cron： 重试队列通过 Perfex CRM 的 cron 任务自动处理
    • 确保 cron 任务正在运行：Setup → Settings → Cron Job
    • cron URL 应该每 5 分钟调用一次
  3. 检查错误消息，在 Sync History 中查看线索最初失败的原因

访问令牌过期​

症状： 连接测试失败并显示 "Token expired" 或线索停止到达。

修复：​

模块将短期令牌交换为 长期令牌（有效期约 60 天）。要刷新：

  1. 前往 Meta Leads → Settings
  2. 滚动到 Connected Pages
  3. 再次点击 "Connect with Facebook"
  4. 登录并授予权限
  5. 令牌将自动刷新
提示

设置提醒 每 50 天重新连接一次以保持令牌有效！

字段映射不正确​

症状： 线索数据出现在错误的字段中或缺失。

调试步骤：​

  1. 前往 Sync History → 点击一条线索条目查看原始数据
  2. 检查 Facebook 发送的 字段名称
  3. 前往 Field Mapping → 确保 Facebook 字段名称匹配
  4. 记住：标准字段（email、full_name、phone_number）会自动映射

常见字段名称问题：​

您期望的Facebook 发送的解决方案
namefull_name已自动映射
phonephone_number已自动映射
companycompany_name已自动映射
budgetcustom_question_1创建自定义映射

安装后模块未出现​

修复：​

  1. 检查文件位置： 模块文件夹必须在 modules/facebookleadsintegration/
  2. 检查文件名： 主文件必须是 facebookleadsintegration.php（全小写）
  3. 激活模块： 前往 Setup → Modules → 点击 Activate
  4. 检查权限： 文件应可被 Web 服务器读取（文件 644，目录 755）

服务器特定问题​

Cloudflare 用户​

如果使用 Cloudflare，请将 Facebook 的 webhook IP 加入白名单：

  1. 前往 Cloudflare → WAF（Web 应用防火墙）
  2. 创建规则 Allow 来自 Facebook 的请求
  3. 或将以下内容添加到您的防火墙白名单：
    • Facebook 的 webhook IP 可在此处找到：https://developers.facebook.com/docs/sharing/webmasters/getting-started/webhooks/

Nginx 用户​

确保您的 Nginx 配置允许对 webhook URL 的 POST 请求，并且不阻止 Facebook 的 User-Agent。

共享主机​

大多数共享主机都能正常工作。如果有问题：

  • 检查 PHP 中 allow_url_fopen 是否已启用
  • 检查 cURL 扩展是否已安装
  • 检查您的主机是否阻止传入的 webhook（某些注重安全的主机会这样做）

仍需帮助？​

如果以上方法都无法解决您的问题：

  1. 检查 Perfex CRM 错误日志
  2. 检查模块的 Sync History 中的错误消息
  3. 截取任何错误消息的截图
  4. 通过 [email protected] 联系我们，并提供：
    • 您的 Perfex CRM 版本
    • PHP 版本
    • 错误消息
    • 重现问题的步骤

查看 FAQ 获取更多答案 FAQ