WhatsApp Business API

官方 Meta Cloud API 集成。详细操作请参阅辅助文件。

快速开始

curl -X POST "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID/messages" 
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"messaging_product":"whatsapp","to":"1234567890","type":"text","text":{"body":"Hello!"}}'

配置

首次使用时，请阅读 setup.md。偏好设置保存在 ~/whatsapp-business-api/memory.md 中。

适用场景

所有 WhatsApp Business 相关操作：发送消息、模板、媒体、交互式组件，管理 Webhook，处理会话，更新企业资料等。

架构

~/whatsapp-business-api/
├── memory.md      # 账户上下文 + 电话号码
├── templates.md   # 已批准模板参考
└── webhooks.md    # Webhook 配置

速查表

核心规则

1. 国际格式 — 电话号码不得包含 + 或前导零：1234567890
2. 24 小时窗口期 — 客户发起消息后 24 小时内可免费回复；主动发起对话必须使用已批准模板
3. 模板审批 — 模板需经 Meta 审批（通常耗时 24–48 小时）；请先在 sandbox 中测试
4. 幂等性 — 使用 biz_opaque_callback_data 追踪消息状态
5. Webhook 签名验证 — 必须始终使用 App Secret 验证 Webhook 签名
6. 速率限制 — 每个电话号码最多 80 条/秒；每账户每日最多发送 1000 条模板消息（Tier 1）
7. 媒体大小限制 — 图片 <5MB，视频 <16MB，文档 <100MB

身份认证

必需的环境变量：

• WHATSAPP_ACCESS_TOKEN — 系统用户访问令牌（永久有效）或用户访问令牌（有效期 60 天）
• WHATSAPP_PHONE_NUMBER_ID — 您注册的电话号码 ID
• WHATSAPP_BUSINESS_ACCOUNT_ID — 您的 WABA ID（用于模板操作）
• WHATSAPP_APP_SECRET — Webhook 签名验证所用的应用密钥

curl "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID" 
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

令牌类型

常见陷阱

• 电话号码含 + 或 00 前缀 → API 拒绝请求
• 缺失 messaging_product: "whatsapp" → 返回 400 错误
• 模板未获批准 → 消息静默失败
• 未验证 Webhook 签名 → 存在安全风险
• 在 24 小时窗口期外未使用模板发送消息 → 请求被拦截

外部端点

安全与隐私

使用的环境变量：

• WHATSAPP_ACCESS_TOKEN — 用于 API 身份认证
• WHATSAPP_APP_SECRET — 用于 Webhook 签名验证

发送至 Meta 的数据：通过 graph.facebook.com 发送的消息、媒体及客户电话号码
仅保留在本地的数据：令牌（绝不记录日志）、~/whatsapp-business-api/ 下的配置文件
绝对禁止的操作：记录消息正文内容、跳过 Webhook 签名验证、将令牌硬编码至代码中

可信度说明

本技能会将数据发送至 Meta（facebook.com/whatsapp）。

相关技能

若用户确认，可通过 clawhub install 安装以下技能：

• api — REST API 设计模式
• webhook — Webhook 处理逻辑
• chat — 对话式交互模式

反馈

• 如认为有用：clawhub star whatsapp-business-api
• 保持更新：clawhub sync