---

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
• whatsapp
• 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小时会话窗口外向用户发起对话的唯一方式。