OpenClaw Skills WhatsApp 商业集成技能使用参考手册

概述

WhatsApp Business 是用于让 OpenClaw 通过 WhatsApp Business API 与 WhatsApp 商业平台交互的 OpenClaw 技能，该技能支持消息收发、客户管理、自动化回复、模板消息、会话管理等功能，通过 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。

该技能可以帮助用户在 OpenClaw 中直接访问和操作 WhatsApp 商业平台的功能，适合需要在 AI 助手中集成 WhatsApp 商业功能的场景，例如客户服务、消息营销、订单通知等。

技能信息

名称：whatsapp-business
描述：通过 WhatsApp Business API 实现消息收发、模板管理和客户交互，使用 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。
版本：1.0.3
作者：maton
许可证：MIT License
依赖：
- 需要网络访问权限
- 需要有效的 Maton API Key（MATON_API_KEY）
触发词："WhatsApp 消息发送"、"WhatsApp 模板管理"、"WhatsApp 客户交互"、"WhatsApp 商业功能"、"WhatsApp 消息营销"

👤 作者：byungkyu
🦞 官方地址：https://clawhub.ai/byungkyu/whatsapp-business
👉 Skills 下载地址：whatsapp-business-1.0.3.zip

快速开始

发送文本消息

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello from WhatsApp Business!'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/whatsapp-business/{native-api-path}

将 {native-api-path} 替换为实际的 WhatsApp Business API 端点路径。网关会将请求代理到 graph.facebook.com，并自动注入你的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量

将你的 API 密钥设置为 MATON_API_KEY 环境变量：

export MATON_API_KEY="你的 API 密钥"

获取 API 密钥

访问 maton.ai 注册或登录账户
进入 maton.ai/settings 页面
复制你的 API 密钥

连接管理

你可以在 https://ctrl.maton.ai 管理你的 WhatsApp Business OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=whatsapp-business&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'whatsapp-business'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "whatsapp-business",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果你有多个 WhatsApp Business 连接，可以通过 Maton-Connection 头指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello!'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早的）活动连接。

API 参考

消息

发送文本消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "1234567890",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Hello! Check out https://example.com"
  }
}

发送模板消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "John"}
        ]
      }
    ]
  }
}

发送图片消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "image",
  "image": {
    "link": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }
}

发送文档消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "document",
  "document": {
    "link": "https://example.com/document.pdf",
    "caption": "Here's the document",
    "filename": "report.pdf"
  }
}

发送视频消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "video",
  "video": {
    "link": "https://example.com/video.mp4",
    "caption": "Watch this video"
  }
}

发送音频消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "audio",
  "audio": {
    "link": "https://example.com/audio.mp3"
  }
}

发送位置消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "San Francisco",
    "address": "San Francisco, CA, USA"
  }
}

发送联系人消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe"
      },
      "phones": [
        {"phone": "+1234567890", "type": "MOBILE"}
      ]
    }
  ]
}

发送交互式按钮消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {"type": "text", "text": "Select an option"},
    "body": {"text": "Choose from the list below"},
    "footer": {"text": "Thank you for your selection"},
    "action": {
      "buttons": [
        {"type": "reply", "reply": {"id": "option1", "title": "Option 1"}},
        {"type": "reply", "reply": {"id": "option2", "title": "Option 2"}},
        {"type": "reply", "reply": {"id": "option3", "title": "Option 3"}}
      ]
    }
  }
}

发送交互式列表消息

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "to": "1234567890",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {"type": "text", "text": "Select an option"},
    "body": {"text": "Choose from the list below"},
    "footer": {"text": "Thank you for your selection"},
    "action": {
      "button": "View Options",
      "sections": [
        {
          "title": "Products",
          "rows": [
            {"id": "prod1", "title": "Product 1", "description": "First product"},
            {"id": "prod2", "title": "Product 2", "description": "Second product"},
            {"id": "prod3", "title": "Product 3", "description": "Third product"}
          ]
        }
      ]
    }
  }
}

上传媒体

POST /whatsapp-business/v21.0/{phone_number_id}/media
Content-Type: multipart/form-data
{
  "messaging_product": "whatsapp",
  "file": "@/path/to/file.jpg",
  "type": "image/jpeg"
}

获取媒体 URL

GET /whatsapp-business/v21.0/{media_id}

删除媒体

DELETE /whatsapp-business/v21.0/{media_id}

消息模板

列出模板

GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates

查询参数：

limit - 返回的模板数量
status - 按状态过滤：APPROVED、PENDING、REJECTED

创建模板

POST /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates
Content-Type: application/json
{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order Confirmation"
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order #{{2}} has been confirmed!"
    },
    {
      "type": "FOOTER",
      "text": "Thank you for your purchase!"
    }
  ]
}

模板类别：AUTHENTICATION、MARKETING、UTILITY

删除模板

DELETE /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates?name=order_confirmation

电话号码

获取电话号码信息

GET /whatsapp-business/v21.0/{phone_number_id}

列出电话号码

GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/phone_numbers

商业资料

获取商业资料

GET /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical

更新商业资料

POST /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile
Content-Type: application/json
{
  "messaging_product": "whatsapp",
  "about": "Your trusted partner",
  "address": "123 Business St",
  "description": "We provide excellent services",
  "email": "contact@example.com",
  "websites": ["https://example.com"],
  "vertical": "RETAIL"
}

代码示例

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
  'Content-Type': 'application/json'
};


// 发送文本消息
await fetch(
  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '1234567890',
      type: 'text',
      text: { body: 'Hello from WhatsApp!' }
    })
  }
);


// 发送模板消息
await fetch(
  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '1234567890',
      type: 'template',
      template: {
        name: 'hello_world',
        language: { code: 'en_US' }
      }
    })
  }
);

Python

import os
import requests


headers = {
  'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
  'Content-Type': 'application/json'
}


## 发送文本消息
response = requests.post(
  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
  headers=headers,
  json={
    'messaging_product': 'whatsapp',
    'to': '1234567890',
    'type': 'text',
    'text': {'body': 'Hello from WhatsApp!'}
  }
)


## 发送模板消息
response = requests.post(
  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
  headers=headers,
  json={
    'messaging_product': 'whatsapp',
    'to': '1234567890',
    'type': 'template',
    'template': {
      'name': 'hello_world',
      'language': {'code': 'en_US'}
    }
  }
)

注意事项

电话号码必须采用国际格式，不带 + 或前导零（例如：1234567890）
messaging_product 必须始终设置为 whatsapp
发起对话需要使用模板消息（24 小时消息窗口）
媒体文件必须是可公开访问的 URL 或通过媒体 API 上传
交互式消息最多支持 3 个按钮或 10 个列表项
消息 ID（wamid）用于跟踪消息状态和回复
当前 API 版本为 v21.0，请查看 Meta 文档获取最新版本
重要提示：使用 curl 命令时，如果 URL 包含括号（fields[]、sort[]、records[]），请使用 curl -g 以禁用 glob 解析
重要提示：当将 curl 输出通过管道传递给 jq 或其他命令时，在某些 shell 环境中，$MATON_API_KEY 等环境变量可能无法正确展开，可能会出现"无效 API 密钥"错误

错误处理

状态码	含义
400	缺少 WhatsApp Business 连接或请求无效
401	Maton API 密钥无效或缺失
404	电话号码或资源未找到
429	速率限制（每个账户每秒 10 次请求）
4xx/5xx	来自 WhatsApp Business API 的传递错误

WhatsApp 常见错误代码：

131030 - 电话号码未注册
131031 - 消息发送失败
132000 - 模板未找到或未批准
133010 - 电话号码达到速率限制

故障排除：API 密钥问题

检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效应用名称

确保你的 URL 路径以 whatsapp-business 开头。例如：
- 正确：https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages
- 错误：https://gateway.maton.ai/v21.0/PHONE_NUMBER_ID/messages

许可证信息

该技能采用 MIT License，完整的许可条款如下：

The MIT License (MIT)
Copyright (c) 2026 Maton


Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:


The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

元数据信息

该技能的元数据信息如下：

{
  "ownerId": "kn75240wq8bnv2qm2xgry748jd80b9r0",
  "slug": "whatsapp-business",
  "version": "1.0.3",
  "publishedAt": 1770756378982
}