跳到主要内容

📱 WhatsApp Cloud API

WhatsApp 通过 Meta 的 Cloud API 连接 — 这是官方的、提供免费层级的 API，让您可以从自己的服务器发送和接收 WhatsApp 消息。不需要第三方 BSP（商业解决方案提供商）。

前提条件​

  1. 在 developers.facebook.com 上的 Meta 开发者账户
  2. 一个 Meta Business 账户（又称 Business Manager）
  3. 一个用于 WhatsApp 的电话号码，且该号码未在个人 WhatsApp 上注册（您可以使用 SIM 卡、虚拟号码或固定电话）

设置步骤​

1. 创建 Meta 应用​

  1. 前往 developers.facebook.com/apps
  2. 点击 Create App
  3. 选择 Business 类型
  4. 填写名称并连接您的 Business 账户

2. 添加 WhatsApp 产品​

  1. 在您的应用面板中，滚动到 Add Products to Your App
  2. 在 WhatsApp 上点击 Set Up
  3. 选择您的 Business 账户

3. 获取您的凭据​

在应用面板中导航至 WhatsApp → API Setup：

凭据在哪里找到
Phone Number ID在 "From" 部分列出 — 一个数字 ID，如 123456789012345
Access Token此页面上显示的临时令牌。对于生产环境，请通过 System Users 生成永久令牌。
App Secret应用面板 → Settings → Basic → App Secret
Verify Token您自己设定的字符串 — 任何随机字符串，例如 my_secret_verify_token_2024

4. 在 PulseHub 中添加渠道​

  1. 前往渠道 → 添加渠道
  2. 选择 WhatsApp
  3. 填写所有四个字段
  4. 点击保存渠道
  5. 复制渠道卡片上显示的 Webhook URL

5. 在 Meta 中配置 Webhook​

  1. 在您的 Meta 应用中，前往 WhatsApp → Configuration
  2. 点击 Webhook 部分旁边的 Edit
  3. Callback URL： 粘贴您的 PulseHub webhook URL
  4. Verify Token： 输入您在 PulseHub 中设置的相同字符串
  5. 点击 Verify and Save

Meta 将向您的 webhook URL 发送 GET 请求，带有 ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...。PulseHub 验证令牌并回传 challenge。

  1. 在 Webhook Fields 下，订阅：messages

6. 测试​

向您的商务号码发送 WhatsApp 消息。它应该在几秒钟内作为新对话出现在 PulseHub 的收件箱中。

签名验证​

Meta 在每个 webhook 中包含 X-Hub-Signature-256 头：

X-Hub-Signature-256: sha256=abc123...

PulseHub 使用您的 App Secret 通过 HMAC-SHA256 进行验证。如果验证失败，webhook 返回 401 Signature mismatch。

发送消息​

当客服从收件箱发送回复时，PulseHub 调用 WhatsApp Cloud API：

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "您的回复内容"}
}

生产环境访问​

默认的 Meta 应用处于 Development 模式 — 只能向添加为测试号码的号码发送消息。要上线：

  1. 在 Meta Business Manager 中完成商业验证
  2. 提交您的 WhatsApp 使用场景进行 Meta 审核
  3. 获批后，您的应用将获得向所有 WhatsApp 用户发送消息的权限

常见问题​

症状可能原因
webhook 设置期间验证失败PulseHub 中的 verify_token 与您在 Meta 中输入的不匹配
日志中的签名不匹配错误app_secret 错误 — 从 App Settings → Basic 复制，而非从 API Setup
消息未到达Meta 面板中未订阅 webhook 字段 messages
发送时 Invalid phone number号码格式必须为 E.164 不带 +（例如 15551234567）
Development 模式应用错误只有已验证的测试号码才能在 dev 模式下接收消息