whatsapp-cloud-api

WhatsApp Cloud API

使用场景

在以下情况下启用此技能：

• 构建或修改 WhatsApp 消息功能
• 发送消息（文本、媒体、模板、交互式消息）
• 处理来自 WhatsApp 的传入 Webhook
• 使用模板消息或会话窗口
• 处理电话号码格式（E.164）
• 调试 WhatsApp API 错误或状态更新
• 实现消息状态跟踪（已发送、已送达、已读）
• 在 WhatsApp Business App 和 Cloud API 上同时运行一个号码（共存）

快速参考

项目	值
基础 URL	https://graph.facebook.com/v21.0
发送消息	POST /{phone-number-id}/messages
上传媒体	POST /{phone-number-id}/media
身份验证	Authorization: Bearer {access-token}
必填字段	"messaging_product": "whatsapp"
电话号码格式	E.164：+{country}{number}（例如，+18091234567）
速率限制	每秒 80 条消息（Cloud API）

核心 API — 发送消息

所有消息都通过同一个端点发送：

POST https://graph.facebook.com/v21.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
Content-Type: application/json

响应：

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+16505555555", "wa_id": "16505555555" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

消息类型

类型	type 字段	详情
文本	text	纯文本，最多 4096 个字符，支持 URL 预览
图片	image	JPEG/PNG，最大 5MB，可选说明文字
视频	video	MP4，最大 16MB，可选说明文字
音频	audio	AAC/MP3/OGG，最大 16MB
文档	document	任意格式，最大 100MB，可选文件名
贴图	sticker	WebP，静态 100KB / 动态 500KB
位置	location	纬度、经度、名称、地址
联系人	contacts	结构化联系人卡片
表情回应	reaction	对消息的表情回应
交互式消息	interactive	按钮、列表、商品
模板	template	预先批准的消息模板

完整规范和代码示例请参阅 references/MESSAGING.md。

Webhook

你的服务器会收到有关传入消息和状态更新的 POST 请求。

传入消息结构：

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "ID", "display_phone_number": "NUM" },
        "contacts": [{ "profile": { "name": "John" }, "wa_id": "16315551234" }],
        "messages": [{
          "from": "16315551234",
          "id": "wamid.ABC...",
          "timestamp": "1683229471",
          "type": "text",
          "text": { "body": "Hello" }
        }]
      },
      "field": "messages"
    }]
  }]
}

状态更新类型： sent → delivered → read | failed

有关 Webhook 验证、负载解析和所有状态类型，请参阅 references/WEBHOOKS.md。

会话窗口

• 客户向你发送消息后，会开启一个 24 小时服务窗口
• 在窗口内：可自由发送任何类型的消息（服务消息免费）
• 在窗口外：只能发送模板消息（按条付费）
• 没有用于“关闭”会话的 API 端点——窗口会自动过期
• 模板消息会按类别（营销、实用、身份验证）开启各自的 24 小时窗口

有关完整生命周期、定价和类别规则，请参阅 references/CONVERSATIONS.md。

共存

在 WhatsApp Business App 和 Cloud API 上同时运行同一个号码——企业可以继续通过应用聊天，同时通过 API 进行集成。

• 通过定制的 Embedded Signup 流程（featureType: "whatsapp_business_app_onboarding"）接入，而非标准注册流程
• 接入时会一次性同步过往消息（history，最多 180 天）和联系人（smb_app_state_sync）
• 企业通过应用发送的消息会通过 smb_message_echoes 镜像到你的 Webhook
• 通过应用发送的消息免费；共存号码的上限为每秒 20 条消息
• 聊天记录会保留；模板消息和 24 小时窗口仍然适用

有关接入、同步、状态检查和 Webhook 负载，请参阅 references/COEXISTENCE.md。

常见模式

发送文本消息

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "text",
  "text": { "body": "Hello! How can we help you?" }
}

发送模板消息

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

将消息标记为已读

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgL..."
}

错误处理

代码	错误	操作
131030	收件人未使用 WhatsApp	发送前验证号码
131047	需要重新互动	先发送模板消息
131050	用户已停止接收营销消息	尊重退订选择，仅发送服务类／实用类消息
131056	触发配对速率限制	降低发送速度，实现退避机制
130429	超出速率限制	将消息加入队列，每秒最多发送 80 条

如需查看完整错误参考和重试策略，请参阅 references/ERROR-CODES.md。

最佳实践

1. 始终使用 E.164 电话号码格式 — +{country}{number}，不含空格或连字符
2. 验证 Webhook — 使用 hub.challenge 值响应 GET 挑战
3. 立即对 Webhook POST 返回 200 — 异步处理
4. 存储 wamid ID — 回复、添加表情反应和已读回执时需要
5. 24 小时窗口过期后，使用模板消息重新互动
6. 处理幂等性 — Webhook 可能会多次传递同一事件
7. 检查 wa_id 与输入值是否一致 — API 会规范化电话号码；wa_id 是规范值
8. 留意速率限制 — Cloud API 每秒最多发送 80 条消息；实现队列和退避机制

参考资料

• 消息 — 所有消息类型
• Webhook — 设置和载荷
• 模板 — 管理和发送
• 会话 — 窗口生命周期和定价
• 共存 — 一个号码同时用于 Business App 和 Cloud API
• 媒体 — 上传、下载和格式
• 交互式消息 — 按钮、列表和商品
• 电话号码 — E.164、ID 和验证
• 错误代码 — 常见错误和重试