WhatsApp 集成¶

ZeroClaw 支持 WhatsApp Business Cloud API 集成。

系统架构¶

WhatsApp 使用 Meta Cloud API 的 Webhook 模式（推送，非轮询）：

用户 → WhatsApp → Meta Server → ZeroClaw Webhook → AI 回复

设置步骤¶

1. 创建 Meta Business App¶

访问 developers.facebook.com
创建新应用 → 选择 "Business" 类型
添加 "WhatsApp" 产品

2. 获取凭证¶

在 WhatsApp → API Setup 中获取：

凭证	说明
Access Token	API 访问令牌
Phone Number ID	电话号码 ID
Verify Token	自定义验证令牌

3. 配置 ZeroClaw¶

[channels_config.whatsapp]
# 从 Meta 获取的凭证
access_token = "EAABx..."
phone_number_id = "123456789012345"

# 你定义的验证令牌（任意字符串）
verify_token = "my-secret-verify-token"

# 允许的号码（E.164 格式）或使用 "*" 允许所有
allowed_numbers = ["+1234567890"]

4. 启动网关并配置隧道¶

由于 WhatsApp 要求 HTTPS，需要使用隧道：

# 使用隧道
zeroclaw gateway --port 8080

# 配置隧道（Cloudflare, Tailscale, 或 ngrok）
# 例如使用 ngrok：
ngrok http 8080
# 获得：https://xxx.ngrok-free.app

5. 配置 Meta Webhook¶

在 Meta Developer Console → WhatsApp → Configuration → Webhook：

Callback URL: https://your-tunnel-url/whatsapp
Verify Token: 与配置中的 verify_token 相同
订阅字段: messages

6. 测试集成¶

向你的 WhatsApp Business 号码发送消息，ZeroClaw 会通过 AI 回复。

验证令牌¶

Webhook 验证流程：

Meta → GET /whatsapp?hub.mode=subscribe&hub.verify_token=secret&hub.challenge=123456
ZeroClaw → 返回 "123456"（验证通过）

配置选项¶

[channels_config.whatsapp]
# Meta 凭证
access_token = "EAABx..."
phone_number_id = "123456789012345"
verify_token = "my-secret-verify-token"

# 号码白名单
allowed_numbers = ["+1234567890"]

# Webhook 端点（可选，默认为 /whatsapp）
webhook_path = "/whatsapp"

# 超时设置
timeout_ms = 15000

号码白名单¶

E.164 格式¶

# 正确格式
allowed_numbers = ["+8613800138000", "+15551234567"]

# 也可以使用国际格式（推荐 + 前缀）
allowed_numbers = ["+15551234567"]

允许所有号码¶

# ⚠️ 仅用于测试
allowed_numbers = ["*"]

消息格式¶

支持¶

✅ 文本消息
✅ 图片
✅ 文档
✅ 语音消息（需转换）

不支持¶

❌ 视频文件（太大）
❌ 位置信息
❌ 联系人名片

媒体回复¶

AI 助手可以发送附件：

[IMAGE:/tmp/chart.png]
[DOCUMENT:/tmp/report.pdf]

隧道选项¶

Cloudflare Tunnel¶

[tunnel]
provider = "cloudflare"

[tunnel.cloudflare]
tunnel_id = "your-tunnel-id"
account_tag = "your-account-tag"

Tailscale Funnel¶

[tunnel]
provider = "tailscale"

[tunnel.tailscale]
hostname = "zeroclaw-whatsapp"
auth_key = "your-auth-key"

ngrok¶

# 安装 ngrok
brew install ngrok

# 启动隧道
ngrok http 8080

# 获得公开 URL
https://xxx.ngrok-free.app

注意： ngrok 免费版 URL 每次启动会变动，需要更新 Webhook 配置。

Webhook 验证¶

手动验证测试¶

# 测试验证端点
curl "https://your-url/whatsapp?hub.mode=subscribe&hub.verify_token=your-token&hub.challenge=test123"

# 应该返回：test123

Meta 自动验证¶

配置 Webhook 后，Meta 会自动发送验证请求。如果成功，Meta 会标记 Webhook 为已验证。

安全考虑¶

1. Access Token 保护¶

# 使用环境变量
export WHATSAPP_ACCESS_TOKEN="EAABx..."

# 或加密存储
[secrets]
encrypt = true

2. Webhook 验证¶

确保 verify_token 是强随机字符串：

# 生成随机令牌
openssl rand -hex 32

3. HTTPS 必需¶

WhatsApp 要求 Webhook 使用 HTTPS：

✅ Cloudflare Tunnel（自动 HTTPS）
✅ Tailscale Funnel（自动 HTTPS）
✅ ngrok（自动 HTTPS）
❌ 直接 IP（不支持）

故障排查¶

Webhook 未验证¶

# 检查日志
zeroclaw gateway --log-level debug

# 手动测试验证
curl "https://your-url/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=TEST"

# 检查 token 是否匹配 allowed_numbers

消息未接收¶

# 检查网络
curl https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 检查白名单
# 是否在 allowed_numbers 中？

网络问题¶

# 测试连接
ping meta.com
curl https://graph.facebook.com

# 检查防火墙
# 确保 443 端口开放

成本和限制¶

WhatsApp Business API 免费版¶

每月 1,000 条免费消息
超过后收费
24 小时对话窗口限制

ZeroClaw 资源占用¶

RAM: <5MB
CPU: <1% 空闲
适合所有订阅等级

消息模板（Marketing）¶

对于主动发送的消息，需要使用模板：

[channels_config.whatsapp.use_templates]
enabled = true
# 从 Meta 创建模板