OpenClaw 接入 WhatsApp：消息推送实战

- 摘要
- 一、引言
- [二、WhatsApp Business API 介绍](#二、WhatsApp Business API 介绍)
- - [2.1 什么是 WhatsApp Business API](#2.1 什么是 WhatsApp Business API)
  - [2.2 核心概念](#2.2 核心概念)
  - [2.3 消息类型](#2.3 消息类型)
  - [2.4 计费模式](#2.4 计费模式)
- [三、Meta 开发者平台配置](#三、Meta 开发者平台配置)
- - [3.1 创建 Meta 开发者账号](#3.1 创建 Meta 开发者账号)
  - [3.2 添加 WhatsApp 产品](#3.2 添加 WhatsApp 产品)
  - [3.3 配置 Webhook](#3.3 配置 Webhook)
  - [3.4 验证 Webhook](#3.4 验证 Webhook)
- [四、OpenClaw WhatsApp 渠道配置](#四、OpenClaw WhatsApp 渠道配置)
- - [4.1 架构概览](#4.1 架构概览)
  - [4.2 配置文件详解](#4.2 配置文件详解)
  - [4.3 环境变量配置](#4.3 环境变量配置)
  - [4.4 启动和验证](#4.4 启动和验证)
- 五、消息模板配置
- - [5.1 为什么需要消息模板](#5.1 为什么需要消息模板)
  - [5.2 创建消息模板](#5.2 创建消息模板)
  - [5.3 在 OpenClaw 中使用模板](#5.3 在 OpenClaw 中使用模板)
  - [5.4 模板消息流程](#5.4 模板消息流程)
- 六、消息推送实战
- - [6.1 接收用户消息](#6.1 接收用户消息)
  - [6.2 消息处理代码示例](#6.2 消息处理代码示例)
  - [6.3 发送富媒体消息](#6.3 发送富媒体消息)
  - [6.4 消息状态追踪](#6.4 消息状态追踪)
- 七、常见问题与解决方案
- - [7.1 Webhook 验证失败](#7.1 Webhook 验证失败)
  - [7.2 消息发送失败](#7.2 消息发送失败)
  - [7.3 模板消息审核不通过](#7.3 模板消息审核不通过)
  - [7.4 消息延迟或丢失](#7.4 消息延迟或丢失)
  - [7.5 签名验证失败](#7.5 签名验证失败)
- 八、最佳实践
- - [8.1 安全建议](#8.1 安全建议)
  - [8.2 性能优化](#8.2 性能优化)
  - [8.3 用户体验](#8.3 用户体验)
- 九、总结
- 参考资料

摘要

本文详细介绍如何将 OpenClaw AI Agent 接入 WhatsApp 消息平台，实现智能消息推送功能。文章从 WhatsApp Business API 的基础概念入手，逐步讲解 Meta 开发者平台的配置流程、OpenClaw 渠道配置、消息模板设置，最终完成一个可实际运行的 WhatsApp AI 助手。通过本文的学习，读者将掌握 WhatsApp 消息推送的完整技术栈，包括 Webhook 配置、消息签名验证、模板消息发送等核心技能，为构建企业级 WhatsApp AI 服务奠定坚实基础。

一、引言

在全球即时通讯市场中，WhatsApp 以超过 20 亿月活跃用户稳居第一，尤其在欧洲、南美、印度等地区拥有极高的渗透率。对于希望触达全球用户的企业和开发者而言，WhatsApp 已成为不可或缺的沟通渠道。

传统的 WhatsApp 机器人开发需要处理复杂的 API 认证、消息格式、模板审核等问题，开发门槛较高。而 OpenClaw 作为一个自托管的 AI Agent 网关，提供了开箱即用的 WhatsApp 集成方案，让开发者能够专注于业务逻辑而非底层协议。

本文将带领读者从零开始，完成 OpenClaw 与 WhatsApp 的完整集成，最终实现一个能够智能回复用户消息的 AI 助手。

二、WhatsApp Business API 介绍

2.1 什么是 WhatsApp Business API

WhatsApp Business API 是 Meta 官方提供的企业级消息接口，允许企业将 WhatsApp 集成到自己的客户服务、营销推广和通知系统中。与个人版 WhatsApp 不同，Business API 支持自动化消息、模板消息、多客服协作等企业级功能。

WhatsApp Business API 有两种接入方式：

接入方式	适用场景	特点
云 API（Cloud API）	中小企业、快速原型	Meta 托管服务器，配置简单，免费额度充足
本地 API（On-Premises API）	大型企业、合规要求	自行部署服务器，数据完全自主，运维成本高

本文推荐使用云 API，它更适合快速开发和中小规模应用。

2.2 核心概念

在使用 WhatsApp Business API 之前，需要理解以下核心概念：

Phone Number ID（电话号码 ID）：每个 WhatsApp Business 账号关联一个或多个电话号码，Phone Number ID 是该号码在 API 中的唯一标识。

WABA ID（WhatsApp Business Account ID）：WhatsApp Business 账号的唯一标识，用于管理多个电话号码和模板消息。

Access Token（访问令牌）：调用 API 的认证凭证，分为临时令牌（有效期 24 小时）和永久令牌（需定期刷新）。

Webhook（回调地址）：当用户发送消息或消息状态变化时，Meta 会向该地址推送事件通知。

Message Template（消息模板）：预先审核的消息格式，用于主动向用户发送消息（用户发起会话后的 24 小时内可自由发送消息）。

2.3 消息类型

WhatsApp Business API 支持多种消息类型：
消息类型
文本消息
媒体消息
交互消息
模板消息
纯文本
图片
视频
音频
文档
按钮
列表
位置请求
认证模板
营销模板
工具模板

2.4 计费模式

WhatsApp Business API 采用对话计费模式，每次对话持续 24 小时：

对话类型	说明	价格（美国）
用户发起	用户主动发送消息触发	$0.00（免费）
企业发起	企业主动发起对话	$0.0135/对话
认证对话	用于身份验证	$0.0135/对话
营销对话	营销推广消息	$0.0250/对话

前 1000 次对话/月免费，适合中小规模应用测试。

三、Meta 开发者平台配置

3.1 创建 Meta 开发者账号

首先，访问 Meta for Developers 平台，使用 Facebook 账号登录。如果没有账号，需要先注册一个 Facebook 账号。

登录后，点击右上角的「我的应用」，然后点击「创建应用」。选择「业务」类型，填写应用名称和联系邮箱。

3.2 添加 WhatsApp 产品

创建应用后，进入应用仪表板，找到「添加产品」部分，选择「WhatsApp」并点击「设置」。

在 WhatsApp 设置页面，你将看到：

临时访问令牌：有效期 24 小时，用于测试 API 调用
测试电话号码：Meta 提供的测试号码，可向最多 5 个验证号码发送消息
Phone Number ID：测试号码的 ID
WABA ID：WhatsApp Business 账号 ID

3.3 配置 Webhook

Webhook 是接收用户消息的关键配置。在 WhatsApp 设置页面找到「Webhook」部分：

步骤一：准备 Webhook 服务器

OpenClaw Gateway 内置了 Webhook 接收功能，只需确保 Gateway 服务已启动：

bash 复制代码

# 启动 OpenClaw Gateway
openclaw gateway start --port 18789

# 检查服务状态
openclaw gateway status

步骤二：配置回调 URL

在 Webhook 配置中填写：

回调 URL ：https://your-domain.com/webhook/whatsapp
验证令牌 ：自定义一个随机字符串，如 openclaw_whatsapp_verify_2024

步骤三：订阅事件

订阅以下 Webhook 字段：

字段名	说明
`messages`	接收用户发送的消息
`message_status`	消息状态更新（已发送、已送达、已读）
`messaging_postbacks`	按钮点击回调

3.4 验证 Webhook

Meta 会向你的 Webhook URL 发送一个 GET 请求进行验证：

http 复制代码

GET /webhook/whatsapp?hub.mode=subscribe&hub.challenge=CHALLENGE_STRING&hub.verify_token=YOUR_VERIFY_TOKEN

OpenClaw 会自动处理这个验证请求，返回 hub.challenge 的值。如果验证令牌匹配，Webhook 配置成功。
配置文件 OpenClaw Gateway Meta 平台配置文件 OpenClaw Gateway Meta 平台 GET /webhook/whatsapp hub.mode=subscribe hub.verify_token=xxx 读取 verify_token 返回配置的 token 验证 token 匹配返回 hub.challenge 标记 Webhook 已验证验证成功通知

四、OpenClaw WhatsApp 渠道配置

4.1 架构概览

在开始配置之前，先了解 OpenClaw 与 WhatsApp 的集成架构：

整个架构分为四层：

用户层：用户通过 WhatsApp App 发送和接收消息
平台层：WhatsApp Business API 和 Meta 开发者平台处理消息路由
网关层：OpenClaw Gateway 负责消息路由、会话管理和安全控制
智能层：AI Agent 处理消息内容，调用工具和技能

4.2 配置文件详解

OpenClaw 使用 YAML 格式的配置文件，WhatsApp 渠道配置位于 channels 部分：

yaml 复制代码

# openclaw-config.yaml
openclaw:
  gateway:
    port: 18789
    auth_token: "your-secure-auth-token"
    public_url: "https://your-domain.com"
  
  channels:
    whatsapp:
      enabled: true
      
      # WhatsApp Business API 凭证
      phone_number_id: "YOUR_PHONE_NUMBER_ID"
      waba_id: "YOUR_WABA_ID"
      access_token: "YOUR_ACCESS_TOKEN"
      
      # Webhook 配置
      webhook:
        verify_token: "openclaw_whatsapp_verify_2024"
        path: "/webhook/whatsapp"
      
      # 消息配置
      messages:
        # 24小时窗口内可自由发送
        session_timeout_hours: 24
        # 模板消息语言
        default_language: "zh_CN"
      
      # 安全配置
      security:
        # 验证消息签名
        verify_signature: true
        # 应用密钥（用于签名验证）
        app_secret: "YOUR_APP_SECRET"

上述配置文件展示了 OpenClaw WhatsApp 渠道的完整配置项。其中 gateway 部分定义了服务端口和公网访问地址，channels.whatsapp 部分包含了 WhatsApp Business API 的核心凭证和配置。phone_number_id 和 waba_id 从 Meta 开发者平台获取，access_token 用于 API 调用认证。Webhook 配置中的 verify_token 需要与 Meta 平台配置一致。security.verify_signature 开启后，OpenClaw 会验证每条消息的签名，确保消息来自 Meta 官方服务器，防止伪造攻击。

4.3 环境变量配置

为了安全起见，建议将敏感信息存储在环境变量中：

bash 复制代码

# ~/.bashrc 或 ~/.zshrc
export OPENCLAW_WHATSAPP_PHONE_NUMBER_ID="your-phone-number-id"
export OPENCLAW_WHATSAPP_WABA_ID="your-waba-id"
export OPENCLAW_WHATSAPP_ACCESS_TOKEN="your-access-token"
export OPENCLAW_WHATSAPP_APP_SECRET="your-app-secret"

然后在配置文件中引用：

yaml 复制代码

channels:
  whatsapp:
    phone_number_id: "${OPENCLAW_WHATSAPP_PHONE_NUMBER_ID}"
    waba_id: "${OPENCLAW_WHATSAPP_WABA_ID}"
    access_token: "${OPENCLAW_WHATSAPP_ACCESS_TOKEN}"
    security:
      app_secret: "${OPENCLAW_WHATSAPP_APP_SECRET}"

4.4 启动和验证

配置完成后，启动 OpenClaw Gateway：

bash 复制代码

# 使用配置文件启动
openclaw gateway start --config openclaw-config.yaml

# 查看日志
openclaw gateway logs --follow

验证配置是否成功：

bash 复制代码

# 检查渠道状态
openclaw channels status whatsapp

# 发送测试消息
openclaw channels test whatsapp --to "+8613800138000" --message "测试消息"

五、消息模板配置

5.1 为什么需要消息模板

WhatsApp 对企业主动发送消息有严格限制：只有在用户发起会话后的 24 小时窗口内，企业才能自由发送消息。超过这个窗口，必须使用预先审核的消息模板。

消息模板分为三类：

模板类型	用途	审核时间
认证模板	身份验证、OTP 验证码	通常几小时内
营销模板	营销推广、活动通知	1-2 天
工具模板	订单确认、预约提醒	通常几小时内

5.2 创建消息模板

在 Meta 开发者平台创建消息模板：

步骤一：进入模板管理

在 WhatsApp 设置页面，点击「消息模板」→「创建模板」。

步骤二：填写模板信息

yaml 复制代码

# 模板示例：订单发货通知
模板名称: order_shipped
模板类型: 工具模板
语言: 中文（简体）- zh_CN
分类: 订单更新

# 模板内容
标题: 订单已发货 📦
正文: |
  您的订单 {{order_id}} 已发货！
  
  物流公司：{{carrier}}
  快递单号：{{tracking_number}}
  
  预计送达时间：{{estimated_delivery}}
  
  感谢您的支持！

按钮:
  - 类型: URL
    文本: 查看物流
    URL: https://tracking.example.com/{{tracking_number}}

步骤三：提交审核

填写完成后提交审核，Meta 会在 24 小时内完成审核。审核通过后，模板状态变为「已批准」。

5.3 在 OpenClaw 中使用模板

OpenClaw 提供了便捷的模板消息发送接口：

typescript 复制代码

// 使用 OpenClaw SDK 发送模板消息
import { OpenClawClient } from '@openclaw/sdk';

const client = new OpenClawClient({
  gatewayUrl: 'https://your-gateway.com',
  authToken: 'your-auth-token'
});

// 发送订单发货通知
await client.channels.whatsapp.sendTemplate({
  to: '+8613800138000',
  templateName: 'order_shipped',
  language: 'zh_CN',
  components: [
    {
      type: 'body',
      parameters: [
        { type: 'text', text: 'ORD-2024-001' },
        { type: 'text', text: '顺丰速运' },
        { type: 'text', text: 'SF1234567890' },
        { type: 'text', text: '3月25日' }
      ]
    },
    {
      type: 'button',
      sub_type: 'url',
      index: 0,
      parameters: [
        { type: 'text', text: 'SF1234567890' }
      ]
    }
  ]
});

上述代码展示了如何使用 OpenClaw SDK 发送模板消息。sendTemplate 方法接收目标号码、模板名称、语言和参数组件。components 数组中的 body 部分对应模板正文中的变量，按顺序填充 {``{order_id}}、{``{carrier}} 等占位符。button 部分用于填充 URL 按钮中的动态参数。这种方式确保消息格式符合 WhatsApp 规范，避免因格式错误导致发送失败。

5.4 模板消息流程

24小时内
超过24小时
有
无
成功
失败
触发事件
检查会话状态
发送自由消息
是否有模板?
发送模板消息
记录待发送
发送成功?
开启新会话窗口
记录失败原因
后续可自由发送
用户收到消息

六、消息推送实战

6.1 接收用户消息

当用户向你的 WhatsApp Business 号码发送消息时，Meta 会通过 Webhook 推送事件到 OpenClaw Gateway。以下是完整的消息处理流程：

6.2 消息处理代码示例

以下是一个完整的 OpenClaw Skill 示例，用于处理 WhatsApp 消息：

python 复制代码

# skills/whatsapp-handler/SKILL.md
---
name: whatsapp-handler
description: 处理 WhatsApp 消息，支持文本、图片、按钮交互
---

# WhatsApp 消息处理器

本技能处理来自 WhatsApp 的各类消息，并生成智能回复。

## 消息类型支持

- 文本消息：直接处理用户文本
- 图片消息：提取图片 URL，可选下载分析
- 按钮点击：处理用户按钮交互
- 位置分享：解析用户分享的地理位置

## 核心逻辑

```python
# main.py
import json
from typing import Dict, Any, Optional

class WhatsAppHandler:
    """WhatsApp 消息处理器"""
    
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self.session_timeout = config.get('session_timeout_hours', 24)
    
    async def process_webhook(self, payload: Dict[str, Any]) -> Optional[Dict]:
        """
        处理 Webhook 回调
        
        Args:
            payload: Meta 推送的完整 JSON 负载
            
        Returns:
            响应消息字典，或 None（无需回复）
        """
        # 验证签名
        if not self._verify_signature(payload):
            return None
        
        # 提取消息内容
        entry = payload.get('entry', [])
        if not entry:
            return None
        
        changes = entry[0].get('changes', [])
        if not changes:
            return None
        
        value = changes[0].get('value', {})
        messages = value.get('messages', [])
        
        if not messages:
            # 可能是状态更新，忽略
            return None
        
        message = messages[0]
        message_type = message.get('type')
        
        # 根据消息类型分发处理
        handler_map = {
            'text': self._handle_text,
            'image': self._handle_image,
            'interactive': self._handle_interactive,
            'location': self._handle_location,
            'document': self._handle_document
        }
        
        handler = handler_map.get(message_type, self._handle_unknown)
        return await handler(message, value)
    
    async def _handle_text(self, message: Dict, context: Dict) -> Dict:
        """处理文本消息"""
        from_number = message.get('from')
        text = message.get('text', {}).get('body', '')
        
        # 构建响应
        response = {
            'messaging_product': 'whatsapp',
            'recipient_type': 'individual',
            'to': from_number,
            'type': 'text',
            'text': {
                'body': f"收到您的消息：{text}\n\n我是 OpenClaw AI 助手，很高兴为您服务！"
            }
        }
        
        return response
    
    async def _handle_image(self, message: Dict, context: Dict) -> Dict:
        """处理图片消息"""
        from_number = message.get('from')
        image = message.get('image', {})
        media_id = image.get('id')
        caption = image.get('caption', '')
        
        # TODO: 下载图片并分析
        
        response = {
            'messaging_product': 'whatsapp',
            'to': from_number,
            'type': 'text',
            'text': {
                'body': f"收到您发送的图片！\n\n图片 ID: {media_id}\n说明: {caption or '无'}"
            }
        }
        
        return response
    
    async def _handle_interactive(self, message: Dict, context: Dict) -> Dict:
        """处理交互消息（按钮点击）"""
        from_number = message.get('from')
        interactive = message.get('interactive', {})
        
        if interactive.get('type') == 'button_reply':
            button_id = interactive['button_reply']['id']
            button_title = interactive['button_reply']['title']
            
            return {
                'messaging_product': 'whatsapp',
                'to': from_number,
                'type': 'text',
                'text': {
                    'body': f"您点击了按钮：{button_title}\n按钮 ID: {button_id}"
                }
            }
        
        return None
    
    def _verify_signature(self, payload: Dict) -> bool:
        """验证消息签名"""
        # OpenClaw Gateway 会自动验证签名
        # 这里可以添加额外的验证逻辑
        return True

上述代码实现了一个完整的 WhatsApp 消息处理器类。process_webhook 方法是入口点，它解析 Meta 推送的 JSON 负载，验证签名，然后根据消息类型分发到对应的处理方法。_handle_text 处理普通文本消息，_handle_image 处理图片消息，_handle_interactive 处理按钮点击等交互事件。每个处理器返回一个符合 WhatsApp API 格式的响应字典，OpenClaw Gateway 会自动将其发送给用户。这种模块化的设计使得添加新的消息类型支持变得非常简单。

6.3 发送富媒体消息

WhatsApp 支持发送图片、视频、文档等富媒体消息：

python 复制代码

async def send_image_message(self, to: str, image_url: str, caption: str = None):
    """发送图片消息"""
    payload = {
        'messaging_product': 'whatsapp',
        'to': to,
        'type': 'image',
        'image': {
            'link': image_url
        }
    }
    
    if caption:
        payload['image']['caption'] = caption
    
    return await self._send_api_request(payload)

async def send_interactive_message(self, to: str, body: str, buttons: list):
    """发送带按钮的交互消息"""
    payload = {
        'messaging_product': 'whatsapp',
        'to': to,
        'type': 'interactive',
        'interactive': {
            'type': 'button',
            'body': {'text': body},
            'action': {
                'buttons': [
                    {
                        'type': 'reply',
                        'reply': {
                            'id': btn['id'],
                            'title': btn['title']
                        }
                    }
                    for btn in buttons
                ]
            }
        }
    }
    
    return await self._send_api_request(payload)

6.4 消息状态追踪

WhatsApp 提供消息状态回调，可以追踪消息的送达和阅读状态：
消息发送
已送达设备
用户已读
发送失败
sent
delivered
read
failed
消息已提交到 WhatsApp 服务器
消息已送达用户设备
用户已打开消息

状态回调处理示例：

python 复制代码

async def handle_message_status(self, payload: Dict):
    """处理消息状态更新"""
    entry = payload['entry'][0]
    changes = entry['changes'][0]
    statuses = changes['value'].get('statuses', [])
    
    for status in statuses:
        message_id = status['id']
        status_type = status['status']
        timestamp = status['timestamp']
        recipient_id = status['recipient_id']
        
        # 记录状态到数据库
        await self.db.update_message_status(
            message_id=message_id,
            status=status_type,
            timestamp=datetime.fromtimestamp(int(timestamp))
        )
        
        # 根据状态触发业务逻辑
        if status_type == 'failed':
            error = status.get('errors', [{}])[0]
            await self.handle_send_failure(message_id, error)

七、常见问题与解决方案

7.1 Webhook 验证失败

问题描述：配置 Webhook 时，Meta 提示验证失败。

解决方案：

确认 Gateway 服务已启动且可公网访问
检查 verify_token 是否与 Meta 平台配置一致
确认 Webhook URL 使用 HTTPS 协议
检查防火墙是否放行 443 端口

bash 复制代码

# 测试 Webhook 可达性
curl -X GET "https://your-domain.com/webhook/whatsapp?hub.mode=subscribe&hub.challenge=test&hub.verify_token=your_token"

# 应返回 "test"

7.2 消息发送失败

问题描述：调用 API 发送消息时返回错误。

常见错误码及解决方案：

错误码	说明	解决方案
401	访问令牌无效或过期	刷新 Access Token
403	权限不足	检查应用权限配置
404	Phone Number ID 不存在	确认 ID 正确
429	请求频率超限	降低发送频率，申请提额
1000	模板未审核或被拒绝	检查模板状态

7.3 模板消息审核不通过

问题描述：提交的消息模板被 Meta 拒绝。

常见原因及修改建议：

内容过于营销化：工具模板应聚焦功能性通知，避免营销词汇
变量使用不当 ：确保变量占位符 {``{var}} 格式正确
缺少示例值：提交时需提供每个变量的示例值
语言不匹配：模板语言需与目标用户语言一致

7.4 消息延迟或丢失

问题描述：用户发送消息后，AI 回复延迟或未收到。

排查步骤：
有日志
无日志
处理慢
处理快
成功
失败
消息延迟/丢失
检查 Webhook 日志
检查处理时间
检查网络连通性
优化 AI 响应
检查 API 调用
检查防火墙/代理
检查 SSL 证书
检查用户号码状态
检查 Access Token
问题解决

7.5 签名验证失败

问题描述：开启签名验证后，消息被拒绝。

解决方案：

OpenClaw 使用 HMAC-SHA256 验证消息签名：

python 复制代码

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, app_secret: str) -> bool:
    """
    验证 Webhook 签名
    
    Args:
        payload: 原始请求体（bytes）
        signature: X-Hub-Signature-256 头的值（格式：sha256=xxx）
        app_secret: 应用密钥
        
    Returns:
        签名是否有效
    """
    if not signature.startswith('sha256='):
        return False
    
    expected_sig = signature[7:]  # 去掉 'sha256=' 前缀
    
    # 计算 HMAC-SHA256
    computed_sig = hmac.new(
        app_secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    # 使用恒定时间比较，防止时序攻击
    return hmac.compare_digest(computed_sig, expected_sig)

上述代码展示了 Webhook 签名验证的实现原理。Meta 在发送 Webhook 请求时，会在 X-Hub-Signature-256 头中携带签名，格式为 sha256=<hex_digest>。验证时，使用 App Secret 作为密钥，对原始请求体计算 HMAC-SHA256，然后与请求头中的签名比较。注意要使用 hmac.compare_digest 而非普通的字符串比较，以防止时序攻击。在 OpenClaw 中，这个验证过程由 Gateway 自动完成，开发者只需确保 app_secret 配置正确即可。

八、最佳实践

8.1 安全建议

永远不要在代码中硬编码凭证：使用环境变量或密钥管理服务
定期轮换 Access Token：建议每 90 天更换一次
开启签名验证：防止伪造请求攻击
限制 Webhook 来源 IP：只允许 Meta 服务器 IP 访问

8.2 性能优化

使用消息队列：高并发场景下，将消息处理异步化
缓存用户会话：减少数据库查询
批量发送：对于群发场景，使用批量 API

8.3 用户体验

设置合理的响应时间：WhatsApp 用户期望快速响应，建议 30 秒内回复
使用交互按钮：减少用户输入，提升体验
提供帮助菜单：让用户了解 AI 能力范围

九、总结

本文系统性地介绍了 OpenClaw 接入 WhatsApp 的完整流程，从 WhatsApp Business API 的基础概念到实际的消息推送实现，涵盖了开发者需要掌握的核心技能。

核心要点回顾：

WhatsApp Business API 是企业接入 WhatsApp 的官方渠道，支持云 API 和本地 API 两种部署方式，云 API 更适合快速开发和中小规模应用。
Meta 开发者平台配置是接入的第一步，包括创建应用、添加 WhatsApp 产品、配置 Webhook 和获取 API 凭证。Webhook 验证是关键环节，需要确保 Gateway 服务可公网访问。
OpenClaw 提供了开箱即用的 WhatsApp 集成，只需在配置文件中填写凭证即可启用。支持环境变量注入，便于安全管理敏感信息。
消息模板是主动触达用户的关键，超过 24 小时会话窗口后必须使用模板消息。模板需要经过 Meta 审核，建议使用工具模板类型，审核通过率更高。
消息处理采用模块化设计，根据消息类型分发到对应的处理器，便于扩展新的消息类型支持。签名验证确保消息安全，防止伪造攻击。

思考与展望：

随着 AI 技术的发展，WhatsApp AI 助手将在客服、营销、通知等场景发挥更大价值。OpenClaw 的多渠道特性使得一套代码可以同时服务 WhatsApp、Telegram、飞书等多个平台，大大降低了开发和维护成本。未来，结合语音识别、图像理解等多模态能力，WhatsApp AI 助手将能够提供更加智能和人性化的服务。

对于希望深入学习 WhatsApp Business API 的开发者，建议阅读 Meta 官方文档，并关注 OpenClaw 社区的最新动态。

OpenClaw 接入 WhatsApp：消息推送实战

目录

摘要

一、引言

二、WhatsApp Business API 介绍

2.1 什么是 WhatsApp Business API

2.2 核心概念

2.3 消息类型

2.4 计费模式

三、Meta 开发者平台配置

3.1 创建 Meta 开发者账号

3.2 添加 WhatsApp 产品

3.3 配置 Webhook

3.4 验证 Webhook

四、OpenClaw WhatsApp 渠道配置

4.1 架构概览

4.2 配置文件详解

4.3 环境变量配置

4.4 启动和验证

五、消息模板配置

5.1 为什么需要消息模板

5.2 创建消息模板

5.3 在 OpenClaw 中使用模板

5.4 模板消息流程

六、消息推送实战

6.1 接收用户消息

6.2 消息处理代码示例

6.3 发送富媒体消息

6.4 消息状态追踪

七、常见问题与解决方案

7.1 Webhook 验证失败

7.2 消息发送失败

7.3 模板消息审核不通过

7.4 消息延迟或丢失

7.5 签名验证失败

八、最佳实践

8.1 安全建议

8.2 性能优化

8.3 用户体验

九、总结

参考资料