Back to Details

whatsapp-cloud-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

WhatsApp Cloud API

WhatsApp Cloud API

When to Use

适用场景

Activate this skill when:
  • Building or modifying WhatsApp messaging features
  • Sending messages (text, media, templates, interactive)
  • Processing incoming webhooks from WhatsApp
  • Working with template messages or conversation windows
  • Handling phone number formatting (E.164)
  • Debugging WhatsApp API errors or status updates
  • Implementing message status tracking (sent, delivered, read)
在以下场景中使用本技能：
  • 构建或修改WhatsApp消息功能
  • 发送消息（文本、媒体、模板、交互式）
  • 处理来自WhatsApp的传入Webhook
  • 处理模板消息或对话窗口
  • 处理电话号码格式化（E.164标准）
  • 调试WhatsApp API错误或状态更新
  • 实现消息状态跟踪（已发送、已送达、已读）

Quick Reference

快速参考

ItemValue
Base URL
https://graph.facebook.com/v21.0
Send Message
POST /{phone-number-id}/messages
Upload Media
POST /{phone-number-id}/media
Auth
Authorization: Bearer {access-token}
Required Field
"messaging_product": "whatsapp"
Phone FormatE.164: 
+{country}{number}
(e.g., 
+18091234567
)
Rate Limit80 messages/second (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标准: 
+{国家码}{号码}
（例如：
+18091234567
）
速率限制80条消息/秒（Cloud API）

Core API — Send Message

核心API — 发送消息

All messages go through a single endpoint:
POST https://graph.facebook.com/v21.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
Content-Type: application/json
Response:
json
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+16505555555", "wa_id": "16505555555" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}
所有消息都通过单一端点发送：
POST https://graph.facebook.com/v21.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
Content-Type: application/json
响应示例：
json
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+16505555555", "wa_id": "16505555555" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

Message Types

消息类型

Type
type
Field		Details
Text
text
Plain text, max 4096 chars, supports URL preview
Image
image
JPEG/PNG, max 5MB, optional caption
Video
video
MP4, max 16MB, optional caption
Audio
audio
AAC/MP3/OGG, max 16MB
Document
document
Any format, max 100MB, optional filename
Sticker
sticker
WebP, static 100KB / animated 500KB
Location
location
latitude, longitude, name, address
Contacts
contacts
Structured contact cards
Reaction
reaction
Emoji reaction to a message
Interactive
interactive
Buttons, lists, products
Template
template
Pre-approved message templates
For full specs and code examples, see references/MESSAGING.md.
类型
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。

Webhooks

Webhook

Your server receives POST requests for incoming messages and status updates.
Incoming message structure:
json
{
  "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"
    }]
  }]
}
Status update types: 
sent
→ 
delivered
→ 
read
| 
failed
For webhook verification, payload parsing, and all status types, see references/WEBHOOKS.md.
你的服务器会收到针对传入消息和状态更新的POST请求。
传入消息结构：
json
{
  "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": "你好" }
        }]
      },
      "field": "messages"
    }]
  }]
}
状态更新类型：
sent
（已发送）→ 
delivered
（已送达）→ 
read
（已读） | 
failed
（发送失败）
关于Webhook验证、负载解析以及所有状态类型，请查看references/WEBHOOKS.md。

Conversation Window

对话窗口

  • When a customer messages you, a 24-hour service window opens
  • Inside the window: send any message type freely (service messages are FREE)
  • Outside the window: only template messages can be sent (paid per message)
  • No API endpoint to "close" a conversation — windows expire automatically
  • Template messages open their own 24h window per category (marketing, utility, auth)
For full lifecycle, pricing, and category rules, see references/CONVERSATIONS.md.
  • 当客户向你发送消息时，会开启一个24小时服务窗口
  • 窗口内：可自由发送任意类型的消息（服务类消息免费）
  • 窗口外：仅能发送模板消息（每条消息需付费）
  • 没有API端点可以“关闭”对话——窗口会自动过期
  • 模板消息会为每个类别（营销、实用、认证）开启独立的24小时窗口
完整生命周期、定价以及类别规则，请查看references/CONVERSATIONS.md。

Common Patterns

常见用法示例

Send a text message

发送文本消息

json
{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "text",
  "text": { "body": "Hello! How can we help you?" }
}
json
{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "text",
  "text": { "body": "你好！我们能为你提供什么帮助？" }
}

Send a template message

发送模板消息

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

Mark a message as read

标记消息为已读

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

Error Handling

错误处理

CodeErrorAction
131030Recipient not on WhatsAppValidate number before sending
131047Re-engagement requiredSend a template message first
131050User stopped marketing messagesRespect opt-out, send only service/utility
131056Pair rate limit hitSlow down, implement backoff
130429Rate limit exceededQueue messages, max 80/sec
For full error reference and retry strategies, see references/ERROR-CODES.md.
错误码错误信息处理建议
131030收件人未使用WhatsApp发送前验证号码有效性
131047需要重新触达用户先发送模板消息
131050用户已停止接收营销消息尊重退订请求，仅发送服务/实用类消息
131056触发配对速率限制降低发送速度，实现退避机制
130429超出速率限制对消息进行排队，最大速率为80条/秒
完整错误参考和重试策略，请查看references/ERROR-CODES.md。

Best Practices

最佳实践

  1. Always use E.164 phone format — 
    +{country}{number}
    , no spaces or dashes
  2. Verify webhooks — Respond to GET challenge with 
    hub.challenge
    value
  3. Return 200 immediately on webhook POST — process asynchronously
  4. Store 
    wamid
    IDs     — Needed for replies, reactions, and read receipts
  5. Use template messages to re-engage after the 24h window expires
  6. Handle idempotency — Webhook may deliver the same event multiple times
  7. Check 
    wa_id
    vs input     — The API normalizes phone numbers; 
    wa_id
    is canonical
  8. Rate limit awareness — 80 msg/sec for Cloud API; implement queue + backoff
  1. 始终使用E.164电话号码格式 — 
    +{国家码}{号码}
    ，不要包含空格或短横线
  2. 验证Webhook — 响应GET挑战请求时返回
    hub.challenge
    的值
  3. 立即返回200状态码处理Webhook的POST请求——后续异步处理内容
  4. 存储
    wamid
    ID     — 回复、反应和已读回执都需要用到该ID
  5. 使用模板消息在24小时窗口过期后重新触达用户
  6. 处理幂等性 — Webhook可能会多次发送同一事件
  7. 检查
    wa_id
    与输入号码     — API会标准化电话号码；
    wa_id
    是标准格式号码
  8. 注意速率限制 — Cloud API的速率限制为80条/秒；实现消息队列和退避机制

References

参考资料

  • Messaging — All message types
  • Webhooks — Setup and payloads
  • Templates — Management and sending
  • Conversations — Window lifecycle and pricing
  • Media — Upload, download, formats
  • Interactive — Buttons, lists, products
  • Phone Numbers — E.164, IDs, verification
  • Error Codes — Common errors and retries
  • 消息功能 — 所有消息类型
  • Webhook — 配置和负载结构
  • 模板消息 — 管理与发送
  • 对话 — 窗口生命周期与定价
  • 媒体文件 — 上传、下载、格式要求
  • 交互式消息 — 按钮、列表、商品卡片
  • 电话号码 — E.164标准、ID、验证
  • 错误码 — 常见错误与重试策略