
关于
WhatsApp Business Cloud API(Meta)集成。消息、模板、HMAC-SHA256 Webhook、客服自动化。提供 Node.js 和 Python 样板代码
name: whatsapp-cloud-api description: 集成 WhatsApp Business Cloud API (Meta)。消息、模板、HMAC-SHA256 Webhooks、客服自动化。Node.js 和 Python 样板代码。 risk: critical source: community date_added: '2026-03-06' author: renat tags:
- messaging
- meta
- webhooks tools:
- claude-code
- antigravity
- cursor
- gemini-cli
- codex-cli
WhatsApp Cloud API - 专业集成
概述
集成 WhatsApp Business Cloud API (Meta)。消息、模板、HMAC-SHA256 Webhooks、客服自动化。Node.js 和 Python 样板代码。
何时使用此技能
- 当用户提到 "whatsapp" 或相关话题时
- 当用户提到 "whatsapp business" 或相关话题时
- 当用户提到 "api whatsapp" 或相关话题时
- 当用户提到 "chatbot whatsapp" 或相关话题时
- 当用户提到 "whatsapp 消息" 或相关话题时
- 当用户提到 "whatsapp 模板" 或相关话题时
不应使用此技能的情况
- 任务与 WhatsApp Cloud API 无关
- 更简单、更具体的工具可以处理该请求
- 用户需要通用帮助而非领域专业知识
工作原理
用于通过 Meta 官方 Cloud API 实现 WhatsApp Business 专业集成的技能。支持 Node.js/TypeScript 和 Python。
概览
WhatsApp Cloud API 是 Meta 官方的 API,用于通过 WhatsApp Business 发送和接收消息。自 2025 年 10 月起,这是唯一支持的选项(本地部署 API 已停用)。
API 版本: Graph API v21.0 (2026)
基础 URL: https://graph.facebook.com/v21.0/{phone-number-id}/messages
认证方式: Bearer Token(生产环境使用 System User Token)
2026 年定价(每条消息):
| 类别 | 费用 | 何时收费 | |----------------|-------------------|-----------------------------------------| | 营销 | $0.025-$0.1365 | 活动、促销 | | 工具类 | $0.004-$0.0456 | 订单确认、状态更新 | | 认证 | $0.004-$0.0456 | OTP、密码重置 | | 服务 | 免费 | 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']}"}
)
return response.json() # {"messaging_product", "contacts", "messages": [{"id"}]}
3. 发送模板消息(24小时窗口外)
模板是在24小时会话窗口外向用户发起对话的唯一方式。
