5分钟接入 WhatsApp Cloud API Webhook，实现自动回复-洪萨配资

5分钟接入 WhatsApp Cloud API Webhook，实现自动回复

一、WhatsApp Cloud API 简介

WhatsApp Cloud API 是 Meta 在 2022 年推出的免费 API 方案，允许企业直接在 Meta 服务器上托管 WhatsApp Business API，无需通过 BSP（Business Solution Provider）中转。

相比传统的 On-Premises API（需要 Docker 部署、自建服务器），Cloud API 的接入门槛大幅降低——不需要企业自备基础设施，只需要一个 Meta 开发者账号和一个验证过的电话号码。

二、环境准备

在开始之前，你需要准备以下内容：

Meta 开发者账号（访问 developers.facebook.com 注册）
一个未注册 WhatsApp 的手机号码（用于测试）
Python 3.10+ 环境
一个公网可达的 HTTPS 服务器（用于接收 Webhook）
ngrok 或类似工具（本地开发时使用）

三、Webhook 配置步骤

3.1 创建 Meta 应用

登录 Meta Developer Portal
点击"创建应用" → 选择"业务"类型
在应用面板中添加 WhatsApp 产品
选择测试号码（系统会自动分配）

3.2 配置 Webhook

{ "object": "whatsapp_business_account", "entry": [{ "id": "BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID" }, "contacts": [{ "profile": { "name": "CUSTOMER_NAME" }, "wa_id": "CUSTOMER_PHONE" }], "messages": [{ "from": "CUSTOMER_PHONE", "id": "MESSAGE_ID", "timestamp": "TIMESTAMP", "text": { "body": "CUSTOMER_MESSAGE" }, "type": "text" }] }, "field": "messages" }] }] }

配图1：Meta Developer Portal 中 Webhook 配置页截图

四、Python 代码实现

以下是一个完整的 Webhook 接收和自动回复示例：

from flask import Flask, request, jsonify import requests import os import hashlib import hmac app = Flask(__name__) # WhatsApp Cloud API 配置 ACCESS_TOKEN = os.getenv("WHATSAPP_ACCESS_TOKEN") PHONE_NUMBER_ID = os.getenv("WHATSAPP_PHONE_NUMBER_ID") VERIFY_TOKEN = os.getenv("WHATSAPP_VERIFY_TOKEN") API_VERSION = "v22.0" def send_message(to_phone, message_text): """发送 WhatsApp 消息""" url = f"https://graph.facebook.com/{API_VERSION}/{PHONE_NUMBER_ID}/messages" headers = { "Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json" } payload = { "messaging_product": "whatsapp", "to": to_phone, "type": "text", "text": {"body": message_text} } response = requests.post(url, json=payload, headers=headers) return response.json() def auto_reply(text): """简陋但实用的自动回复逻辑""" triggers = { "价格": "WADesk 个人版每月 ¥99 起，提供完整 WhatsApp CRM 功能。了解更多：https://wadesk.io/cn/pricing", "试用": "欢迎免费试用 WADesk！访问 https://wadesk.io/cn 注册即可开通。", "API": "WADesk 支持完整的 WhatsApp Cloud API 和 On-Premises API 接入。", } for keyword, reply in triggers.items(): if keyword in text: return reply return "您好！我们已收到您的消息，客服会在工作时间回复。紧急问题可直接访问 https://wadesk.io/cn" @app.route("/webhook", methods=["GET", "POST"]) def webhook(): if request.method == "GET": # Meta 验证 Webhook URL mode = request.args.get("hub.mode") token = request.args.get("hub.verify_token") challenge = request.args.get("hub.challenge") if mode == "subscribe" and token == VERIFY_TOKEN: return challenge, 200 return "Forbidden", 403 if request.method == "POST": data = request.json print(f"[DEBUG] 收到 Webhook: {data}") # 处理消息 try: messages = data["entry"][0]["changes"][0]["value"].get("messages", []) for msg in messages: if msg.get("type") == "text": from_phone = msg["from"] text = msg["text"]["body"] reply = auto_reply(text) send_message(from_phone, reply) print(f"[OK] 回复 {from_phone}: {reply[:50]}...") except Exception as e: print(f"[ERROR] 处理消息失败: {e}") return jsonify({"status": "ok"}), 200 # 本地开发时使用 ngrok # ngrok http 5000 # 然后将生成的 HTTPS URL 填入 Meta 的 Webhook URL if __name__ == "__main__": app.run(port=5000, debug=True)

五、常见踩坑与解决方案

踩坑 1：Webhook 验证失败

原因：Meta 的 Webhook 验证使用 GET 请求，需要正确返回 challenge 值。

解决：确保VERIFY_TOKEN与 Meta 后台配置一致，且服务器在 30 秒内响应。

踩坑 2：消息发送返回 Error 403

原因：电话号码未通过 Meta 验证，或者模板消息不符合规范。

解决：在 Meta 后台完成电话号码验证，使用通过审核的消息模板发送首条消息（24小时窗口内可自由对话）。

踩坑 3：ngrok 免费版断线

原因：ngrok 免费版连接不稳定，且有带宽限制。

解决：生产环境使用云服务器（阿里云/腾讯云的轻量服务器即可，每月几十块钱），部署真实 HTTPS 服务。

六、进阶：接入 WADesk 实现多账号管理

当你需要管理多个 WhatsApp 号码时，手动维护每个号码的 Webhook 和 API 配置会变得非常繁琐。WADesk 提供了统一的管理后台：

一处配置：所有号码的 API 配置集中管理
自动回复引擎：关键词匹配 + AI 智能回复 + 话术库
多账号分配：客服团队可按规则分配客户消息
聊天记录归档：所有对话自动保存，支持搜索和导出

切换方式很简单：在 WADesk 中填写你的 Meta App 的 Access Token，系统会自动完成 Webhook 注册和消息路由配置。

本文基于 WhatsApp Cloud API v22.0 编写，代码已在 Python 3.12 + Flask 3.0 环境下验证通过。

5分钟接入 WhatsApp Cloud API Webhook，实现自动回复