WhatsApp Business 云 API 接入

这篇教程教你如何把 Hermes Agent 这个 AI 智能体接到 WhatsApp 上，让它用官方正规渠道帮你收发消息——就像给机器人办了一张“企业工牌”，而不是偷偷用个人账号。

先搞懂：云 API 和“野路子”的区别

想象一下，你有两条路让机器人用 WhatsApp：

• 云 API（本篇）：像开一家正规公司，需要营业执照（Meta 企业账号）、固定办公地址（公网 URL），但稳定、安全、不怕封号。
• Baileys 桥接（下篇讲）：像借朋友的手机用，不用办手续，但随时可能被 WhatsApp 封掉那个号码。

做正经生意、长期运营，选云 API；自己玩玩、快速演示，选 Baileys。

准备工作（4 样东西）

1. Meta 企业账号——去 business.facebook.com 免费注册。
2. 一个启用了 WhatsApp 的 Meta 应用——下面第 1 步教你怎么建。
3. 一条把本地服务暴露到公网的通道——推荐 Cloudflare Tunnel（免费、不用公网 IP、不用域名）。
4. （建议装）ffmpeg——让机器人发的语音变成 WhatsApp 原生的绿色声波气泡，而不是文件附件。

第 1 步：创建 Meta 应用

1. 打开 developers.facebook.com/apps → 创建应用。
2. 选择用途：“通过 WhatsApp 与客户联系” → 下一步。
3. 选或新建一个商务管理组合，确认后点创建应用。
4. 进入 API Setup 页面，确认已自动关联了一个 WhatsApp 商业账号（WABA）。

💡 最容易踩的坑：仪表盘上有两个长得像的数字——Phone Number ID（15~17 位数字）和电话号码（带国家区号）。千万别把电话号码填到 Phone Number ID 的框里！ 填错了消息根本发不出去。

第 2 步：拿到 4 个关键凭证

凭证	去哪找	长什么样
Phone Number ID	API Setup 页“From”下拉框下方	纯数字，15~17 位
Access Token	API Setup 页“Generate access token”	以 EAA 开头，100+ 字符
App Secret	设置 → 基础 → 点“显示”	32 位小写十六进制
App ID（可选）	设置 → 基础	15~16 位数字

第 3 步：跑起配置向导

hermes whatsapp-cloud

这个向导会一步步问你每个凭证，你粘贴一个它校验一个（能当场发现你填错字段），最后还会打印出后续操作指引。

第 4 步：把 Hermes 暴露到公网

Meta 需要通过 webhook 把消息推给你，所以你的机器人得有个公网地址。最简单的方式：

cloudflared tunnel --url http://localhost:8090

运行后会打印一个 https://随机名.trycloudflare.com 的地址——这就是你要填给 Meta 的“收件地址”。

⚠️ 免费临时隧道每次重启地址都会变。想要固定地址，用 cloudflared tunnel login 登录后创建命名隧道（免费版不限数量）。

第 5 步：配置 Meta 的 Webhook

1. 生成一个验证令牌（向导会自动生成；手动配置就运行 python -c "import secrets; print(secrets.token_urlsafe(32))"）。
2. 启动网关：hermes gateway。
3. 在 Meta 应用后台 → WhatsApp → Configuration → Webhook 点“编辑”：
   • Callback URL：https://你的隧道地址/whatsapp/webhook
   • Verify Token：上一步生成的字符串（必须完全一致）
4. 点“验证并保存”，Meta 会发一个测试请求，网关自动回应，显示“已验证”。
5. 在 Webhook fields 里订阅 messages 字段——不订阅这个，Meta 不会把消息推给你。

第 6 步：设置白名单（两层）

• Meta 侧：开发模式下，机器人只能给最多 5 个你手动添加的号码发消息（API Setup → 管理电话号码列表，每个号码会收到验证码）。
• Hermes 侧：在 ~/.hermes/.env 里加：

# 逗号分隔，国家代码+号码，不要加号/空格/横线
WHATSAPP_CLOUD_ALLOWED_USERS=15551234567,15557654321

第 7 步：换成永久令牌（上线必做）

临时令牌 24 小时就过期。生产环境请用系统用户令牌：

1. business.facebook.com → 设置 → 系统用户 → 添加（角色选管理员）。
2. 给该用户分配资产：应用（管理应用）+ WhatsApp 账号（管理 WhatsApp 商业账号）。
3. 生成令牌，勾选 business_management、whatsapp_business_messaging、whatsapp_business_management 三个权限。
4. 过期时间选“永不过期”，复制到 ~/.hermes/.env 的 WHATSAPP_CLOUD_ACCESS_TOKEN，重启网关。

最后提醒：24 小时服务窗口

用户发消息后 24 小时内你可以自由回复；超过 24 小时就只能用预先审核通过的模板消息——这是 Meta 的规矩，不是 Hermes 的限制。

---

总结一下：云 API 接入 = 企业账号 + 4 个凭证 + 公网隧道 + 两层白名单 + 永久令牌。向导会帮你搞定大部分配置，剩下的就是等 Meta 审核。

下篇预告：不想办企业账号？我们讲讲用 Baileys 桥接让机器人“借”个人号跑起来——虽然有点野，但胜在快。