5分钟接入 WhatsApp Cloud API Webhook实现自动回复目录WhatsApp Cloud API 简介环境准备Webhook 配置步骤Python 代码实现常见踩坑与解决方案进阶接入 WADesk 实现多账号管理一、WhatsApp Cloud API 简介WhatsApp Cloud API 是 Meta 在 2022 年推出的免费 API 方案允许企业直接在 Meta 服务器上托管 WhatsApp Business API无需通过 BSPBusiness Solution Provider中转。相比传统的 On-Premises API需要 Docker 部署、自建服务器Cloud API 的接入门槛大幅降低——不需要企业自备基础设施只需要一个 Meta 开发者账号和一个验证过的电话号码。二、环境准备在开始之前你需要准备以下内容Meta 开发者账号访问 developers.facebook.com 注册一个未注册 WhatsApp 的手机号码用于测试Python 3.10 环境一个公网可达的 HTTPS 服务器用于接收 Webhookngrok 或类似工具本地开发时使用三、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 }] }] }配图1Meta 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 fhttps://graph.facebook.com/{API_VERSION}/{PHONE_NUMBER_ID}/messages headers { Authorization: fBearer {ACCESS_TOKEN}, Content-Type: application/json } payload { messaging_product: whatsapp, to: to_phone, type: text, text: {body: message_text} } response requests.post(url, jsonpayload, headersheaders) 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(port5000, debugTrue)五、常见踩坑与解决方案踩坑 1Webhook 验证失败原因Meta 的 Webhook 验证使用 GET 请求需要正确返回 challenge 值。解决确保VERIFY_TOKEN与 Meta 后台配置一致且服务器在 30 秒内响应。踩坑 2消息发送返回 Error 403原因电话号码未通过 Meta 验证或者模板消息不符合规范。解决在 Meta 后台完成电话号码验证使用通过审核的消息模板发送首条消息24小时窗口内可自由对话。踩坑 3ngrok 免费版断线原因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 环境下验证通过。