WhatsApp Business — WhatsApp 商业版

通过托管 OAuth 认证访问 WhatsApp Business API。发送消息、管理消息模板、处理媒体文件，并通过 WhatsApp 与客户互动。

快速开始

# 发送文本消息
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/{原生API路径}

将 {原生API路径} 替换为实际的 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')
resp = json.load(urllib.request.urlopen(req))
print(f"请在浏览器中打开以下链接授权:\n{resp['auth_url']}")
EOF

消息操作

发送文本消息

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'messaging_product': 'whatsapp',
    'to': '手机号码（如8613812345678）',
    'type': 'text',
    'text': {'body': '您的验证码是 123456，请在 5 分钟内使用。'}
}).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))))
EOF

发送图片消息

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'messaging_product': 'whatsapp',
    'to': '手机号码',
    'type': 'image',
    'image': {
        'link': 'https://example.com/image.jpg',
        'caption': '产品图片'
    }
}).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))))
EOF

发送模板消息

WhatsApp Business 模板消息需要预先在 Meta 商业平台审核通过。

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'messaging_product': 'whatsapp',
    'to': '手机号码',
    'type': 'template',
    'template': {
        'name': '模板名称（如 hello_world）',
        'language': {'code': 'zh_CN'},
        'components': [
            {
                'type': 'body',
                'parameters': [
                    {'type': 'text', 'text': '客户姓名'}
                ]
            }
        ]
    }
}).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))))
EOF

消息模板管理

查询模板列表

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/message_templates')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

接收消息

设置 Webhook（接收消息）

通过 Webhook 接收客户发送的消息，需要在 Meta 开发者平台配置回调 URL。

消息通过 Maton 网关接收，技能可处理以下消息类型：

• 文本消息
• 图片、音频、视频、文档
• 位置信息
• 按钮回复

# Webhook 接收消息示例
from flask import Flask, request, jsonify
import os
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def receive_message():
    data = request.json
    entry = data['entry'][0]['changes'][0]['value']
    if 'messages' in entry:
        message = entry['messages'][0]
        print(f"收到来自 {message['from']} 的消息: {message}")
    return jsonify({'status': 'ok'})

错误处理

常见错误码：

最佳实践

• 消息频率控制：WhatsApp Business API 对消息发送频率有限制，避免短时间内发送大量消息
• 模板消息审核：商业通知类消息必须使用审核通过的模板
• 隐私合规：收集和使用用户手机号时遵守当地隐私法规
• 错误重试：网络错误时适当重试，但避免过度重试导致被限流