whatsapp-cloud-api

WhatsApp Cloud API - 专业集成

范围与快照：示例面向较旧的 Graph API 版本，并非 Meta 当前的合约。使用前，请在 Meta 官方文档和实际账户中核实受支持的版本、定价、消息/吞吐量限制、模板编辑规则和资格要求。法律表格仅供参考，并非普遍适用的 GDPR/LGPD 要求。发送消息、删除模板、账户迁移、购买、隧道和部署均须在用户授权的范围内进行。确认确切的收件人/内容以及适用的同意要求/服务窗口。切勿记录令牌、个人消息正文或完整的 API 错误。样板代码仅用于本地演示：生产环境需要在确认前持久化入队、经过身份验证的账户路由、幂等性/重放保护、退订检查和工作进程；仅有 HMAC 无法防止重放攻击。

概述

与 WhatsApp Business Cloud API（Meta）集成。支持消息、模板、HMAC-SHA256 Webhook 和客服自动化。提供 Node.js 和 Python 样板代码。

何时使用此技能

• 用户提到“whatsapp”或相关主题时
• 用户提到“whatsapp business”或相关主题时
• 用户提到“api whatsapp”或相关主题时
• 用户提到“chatbot whatsapp”或相关主题时
• 用户提到“mensagem whatsapp”或相关主题时
• 用户提到“template whatsapp”或相关主题时

何时不要使用此技能

• 任务与 WhatsApp Cloud API 无关
• 更简单、更具体的工具可以处理该请求
• 用户需要不涉及领域专业知识的通用帮助

工作原理

用于使用 Meta 官方 Cloud API 实现专业 WhatsApp Business 集成的技能。支持 Node.js/TypeScript 和 Python。

概述

WhatsApp Cloud API 是 Meta 的官方 API，用于通过 WhatsApp Business 发送和接收消息。自 2025 年 10 月起，这是唯一受支持的选项（On-Premises API 已弃用）。

示例版本： Graph API v21.0（使用前请确认是否受支持）
基础 URL： https://graph.facebook.com/v21.0/{phone-number-id}/messages
身份验证： Bearer Token（生产环境使用 System User Token）

2026 年定价（按消息计费）：

类别	费用	收费时间
Marketing	$0.025-$0.1365	营销活动、促销
Utility	$0.004-$0.0456	订单确认、更新
Authentication	$0.004-$0.0456	OTP、密码重置
Service	免费	在 24 小时窗口内回复

前提条件：

• Meta Business Suite 账户（免费）
• Meta for Developers 中包含 WhatsApp 产品的应用
• 已验证的电话号码
• System User Token（永久）

如果用户没有 Meta Business 账户，请阅读 references/setup-guide.md，了解从零开始设置的完整指南。

---

决策树

使用此决策树确定下一步：

O usuario precisa de setup inicial?
├── SIM → Leia references/setup-guide.md
└── NAO → Qual linguagem?
    ├── Node.js/TypeScript
    └── Python
    → O que quer fazer?
       ├── Enviar mensagens → Secao "Tipos de Mensagem" abaixo
       ├── Receber mensagens → Secao "Webhooks" abaixo
       ├── Automatizar atendimento → Secao "Automacao" abaixo
       ├── WhatsApp Flows / Commerce → Secao "Features Avancados" abaixo
       ├── Gerenciar templates → references/template-management.md
       └── Compliance / limites → Secao "Compliance & Quality" abaixo

要使用现成样板代码从零开始创建项目，请使用脚本：

python scripts/setup_project.py --language nodejs --path ./meu-projeto

## Ou

python scripts/setup_project.py --language python --path ./meu-projeto

---

1. 配置环境变量

WHATSAPP_TOKEN=seu_access_token_aqui
PHONE_NUMBER_ID=seu_phone_number_id
WABA_ID=seu_whatsapp_business_account_id
APP_SECRET=seu_app_secret
VERIFY_TOKEN=token_customizado_para_webhook

2. 发送简单文本消息

Node.js/TypeScript：

import axios from 'axios';

const GRAPH_API = 'https://graph.facebook.com/v21.0';

async function sendText(to: string, message: string) {
  const response = await axios.post(
    `${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`,
    {
      messaging_product: 'whatsapp',
      to,
      type: 'text',
      text: { body: message }
    },
    { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } }
  );
  return response.data; // { messaging_product, contacts, messages: [{ id }] }
}

Python：

import httpx
import os

GRAPH_API = "https://graph.facebook.com/v21.0"

async def send_text(to: str, message: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{GRAPH_API}/{os.environ['PHONE_NUMBER_ID']}/messages",
            json={
                "messaging_product": "whatsapp",
                "to": to,
                "type": "text",
                "text": {"body": message}
            },
            headers={"Authorization": f"Bearer {os.environ['WHATSAPP_TOKEN']}"}
        )
        response.raise_for_status()
        return response.json()  # {"messaging_product", "contacts", "messages": [{"id"}]}

3. 发送模板消息（超出 24 小时窗口）

超出客服窗口后，请使用已获批准且符合适用同意要求的模板。模板必须经 WhatsApp 批准后才能使用。

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" }
        ]
      }
    ]
  }
}

4. 验证送达情况

使用测试脚本进行验证：

python scripts/send_test_message.py --to 5511999999999 --message "Teste de integracao"

---

消息类型

类型	用途	限制
文本	简单文本消息	4096 个字符
模板	开始对话 / 超出 24 小时窗口	正文 1600 个字符
图片	照片和图片	5MB
文档	PDF、电子表格、文档	100MB
视频	视频	16MB
音频	语音消息	16MB
交互式按钮	快速回复按钮	最多 3 个按钮
交互式列表	包含分区选项的菜单	最多 10 个选项
位置	分享位置	经纬度
联系人	分享联系人	vCard 格式
表情回应	用表情回应消息	1 个表情

示例 - 交互式按钮（Node.js）：

async function sendButtons(to: string, body: string, buttons: Array<{id: string, title: string}>) {
  return axios.post(`${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`, {
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'button',
      body: { text: body },
      action: {
        buttons: buttons.map(b => ({
          type: 'reply',
          reply: { id: b.id, title: b.title }
        }))
      }
    }
  }, { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } });
}

// Uso:
await sendButtons('5511999999999', 'Como posso ajudar?', [
  { id: 'suporte', title: 'Suporte' },
  { id: 'vendas', title: 'Vendas' },
  { id: 'info', title: 'Informacoes' }
]);

有关 Node.js 和 Python 中所有类型的完整示例，请阅读 references/message-types.md。

---

Webhook

Webhook 允许实时接收消息和状态更新。

验证（Get）- 必需

在 Meta Developers 中配置 webhook 时，Meta 会发送 GET 请求进行验证：

// Node.js (Express)
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

接收（Post）- 使用 Hmac-Sha256 确保安全

每条 webhook 通知都带有 X-Hub-Signature-256 标头签名。处理前务必验证：

import crypto from 'crypto';

function validateSignature(rawBody: Buffer, signature: string): boolean {
  const expectedSig = crypto
    .createHmac('sha256', process.env.APP_SECRET!)
    .update(rawBody)
    .digest('hex');
  if (!/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  const expected = Buffer.from(`sha256=${expectedSig}`);
  const received = Buffer.from(signature);
  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

重要： 使用 crypto.timingSafeEqual（Node.js）或 hmac.compare_digest（Python）来防止时序攻击。切勿使用简单的字符串比较。

接收的事件

• messages - 客户端消息（文本、媒体、按钮、位置）
• statuses - 状态更新（sent → delivered → read）
• errors - 投递错误

要求：

• 使用有效 SSL 证书的 HTTPS 端点
• 在 5 秒内返回 HTTP 200
• 开发环境：使用 ngrok 进行本地测试

有关完整设置及 Node.js 和 Python 示例，请阅读 references/webhook-setup.md。

---

交互式主菜单

使用按钮或列表，在首次交互时创建选项菜单：

## Python - Menu Com Lista Interativa

async def send_main_menu(to: str):
    await send_interactive_list(
        to=to,
        header="Bem-vindo!",
        body="Selecione o que precisa:",
        button_text="Ver opcoes",
        sections=[{
            "title": "Atendimento",
            "rows": [
                {"id": "suporte", "title": "Suporte Tecnico", "description": "Ajuda com problemas"},
                {"id": "vendas", "title": "Vendas", "description": "Conhecer nossos produtos"},
                {"id": "financeiro", "title": "Financeiro", "description": "Boletos e pagamentos"},
            ]
        }]
    )

工作流状态机

使用状态机管理对话。每个客户端都有一个当前状态，用于决定如何处理下一条消息：

INICIO → MENU_PRINCIPAL → SUPORTE → AGUARDANDO_DETALHES → ESCALACAO_HUMANO
                        → VENDAS → CATALOGO → CHECKOUT
                        → FINANCEIRO → SEGUNDA_VIA_BOLETO

24 小时窗口

• 在窗口内（距客户端上次发送消息 24 小时内）： 可以免费发送任何类型的消息
• 超出窗口： 只能发送模板消息（按类别收费）

与 AI 集成（Claude Api）

将 WhatsApp 与 Claude 结合，生成智能回复：

1. 通过 webhook 接收消息
2. 将消息及对话上下文发送至 Claude API
3. 通过 WhatsApp 返回回复
4. 保留人工升级处理选项

有关完整的自动化模式，请阅读 references/automation-patterns.md。

---

WhatsApp Flows

WhatsApp 内的多屏交互式表单。客户端无需离开应用即可填写字段。表单以 JSON 定义，包含 screens、components 和 actions。

使用场景：注册、预约、NPS 调查、产品选择。

Commerce 和目录

WhatsApp 目录最多可容纳 500 个产品。发送单个产品或多产品消息，并通过应用内结账。

模板管理 API

以编程方式创建、列出和删除模板。每个账户最多支持 6000 种翻译。几分钟内即可获批。

WhatsApp Channels

面向无限订阅者的单向广播。位于 WhatsApp 的“更新”选项卡中。

点击进入 WhatsApp 广告

在 Facebook/Instagram 上投放带有按钮的广告，点击后即可打开 WhatsApp 对话。效果因情况而异；不保证转化率。

状态跟踪

跟踪送达状态：待处理 → 服务端 → 设备 → 已读。通过状态更新 webhook 接收通知。

有关高级功能的完整详情，请阅读 references/advanced-features.md。 有关通过 API 管理模板，请阅读 references/template-management.md。

---

核心检查清单

• 发送消息前已获得明确的选择加入同意
• 已实现退订机制（关键词「SAIR」或「STOP」）
• 已记录同意信息，包括时间戳、方式和目的
• 内容符合 WhatsApp 政策（无垃圾信息、无违禁内容）
• 符合 LGPD/GDPR（已确定法律依据，并保障数据主体权利）
• 消息频率适当（不过量）
• 模板已获批后再使用
• 已完成企业验证（以获得更高限额）

质量评级

WhatsApp 会监控消息质量并进行评级：

评级	含义	操作
绿色	质量良好，屏蔽次数少	保持现状——符合升级资格
黄色	质量一般，需要注意	检查内容和发送频率
红色	质量较差，有暂停风险	立即采取行动：降低发送量

积极信号： 回复率高、互动活跃、屏蔽次数少 消极信号： 被屏蔽、被举报为垃圾信息、互动率低

层级系统（消息限额）

自 2025 年 10 月起，限额按 Business Portfolio 计算（而非按号码计算）：

层级	对话数/24h	如何达到
初始	250	新账号／未经验证
Tier 1	1,000	自动升级：连续 7 天使用 50% 以上限额
Tier 2	10,000	自动升级：连续 7 天使用 50% 以上限额
Tier 3	100,000	自动升级：连续 7 天使用 50% 以上限额
Unlimited	不限量	自动升级：连续 7 天使用 50% 以上限额

2026 年变更： 将移除 2K 和 10K 层级。完成企业验证后，限额立即提高至 100K。

有关完整的合规指南，请阅读 references/compliance.md。

---

故障排除

问题	可能原因	解决方案
401 Unauthorized	令牌已过期或无效	生成新的 System User Token
400 Bad Request	请求负载格式错误	对照示例检查 JSON
模板被拒绝	内容违反政策	检查并修改后重新提交
Webhook 未收到通知	URL 无效或未使用 HTTPS	使用 ngrok（开发环境）或 SSL 证书（生产环境）
Rate limit exceeded	超过 80 条消息/秒	实现带重试机制的队列
质量评级低	被大量屏蔽／举报	降低发送量，改进内容
消息未送达	号码无效或未注册 WhatsApp	发送前验证号码
号码未验证	未完成 OTP 验证	通过 SMS 或电话重新验证

验证配置：

python scripts/validate_config.py

---

参考资料（按需阅读）

文件	阅读时机
references/setup-guide.md	初始设置 — 创建 Meta 账户、配置 API
references/message-types.md	所有消息类型的完整示例
references/webhook-setup.md	使用 HMAC 安全配置 Webhook
references/automation-patterns.md	聊天机器人、队列、状态机、AI 集成
references/compliance.md	LGPD/GDPR、opt-in、质量评级、层级系统
references/api-reference.md	端点、错误、速率限制、2026 年定价
references/advanced-features.md	Flows、Commerce、Channels、Ads、状态跟踪
references/template-management.md	通过 API 对模板执行 CRUD

脚本

脚本	功能
scripts/setup_project.py	使用样板代码创建项目（Node.js 或 Python）
scripts/validate_config.py	验证凭据和 API 连接
scripts/send_test_message.py	发送测试消息以验证设置

样板代码

目录	内容
assets/boilerplate/nodejs/	完整的 TypeScript/Express 项目
assets/boilerplate/python/	完整的 Python/Flask 项目
assets/examples/	JSON 负载示例（模板、Webhook、flows）

最佳实践

• 提供有关项目和需求的清晰、具体的上下文
• 在将任何建议应用到生产代码之前，先进行审核
• 与其他互补技能结合使用，以进行全面分析

常见问题

• 将此技能用于超出其专业范围的任务
• 未了解具体上下文便应用建议
• 未提供足够的项目上下文，导致分析不准确

相关技能

• instagram - 用于增强分析的互补技能
• social-orchestrator - 用于增强分析的互补技能
• telegram - 用于增强分析的互补技能

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境的验证、测试或专家审核的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并要求澄清。