WhatsApp Business

通过托管的 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/{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="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或注册账户，请访问maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

连接管理

请在以下地址管理您的 WhatsApp Business OAuth 连接：https://ctrl.maton.ai。

列出连接

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": "你好！查看 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": "看看这张图片！"
  }
}

发送文档消息

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": "这是文档",
    "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": "观看这个视频"
  }
}

发送音频消息

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",
    "body": {
      "text": "Would you like to proceed?"
    },
    "action": {
      "buttons": [
        {"type": "reply", "reply": {"id": "yes", "title": "Yes"}},
        {"type": "reply", "reply": {"id": "no", "title": "No"}}
      ]
    }
  }
}

发送交互式列表消息

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"},
    "action": {
      "button": "View Options",
      "sections": [
        {
          "title": "Products",
          "rows": [
            {"id": "prod1", "title": "Product 1", "description": "First product"},
            {"id": "prod2", "title": "Product 2", "description": "Second product"}
          ]
        }
      ]
    }
  }
}

将消息标记为已读

POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.xxxxx"
}

媒体

上传媒体

POST /whatsapp-business/v21.0/{phone_number_id}/media
Content-Type: multipart/form-data

file=@/path/to/file.jpg
type=image/jpeg
messaging_product=whatsapp

获取媒体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- 按状态筛选：已批准,待处理,已拒绝

创建模板

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": "订单确认"
    },
    {
      "type": "BODY",
      "text": "您好 {{1}}，您的订单 #{{2}} 已确认！"
    },
    {
      "type": "FOOTER",
      "text": "感谢您的购买"
    }
  ]
}

模板类别：认证,营销,实用

删除模板

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

电话号码

获取电话号码

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": "您值得信赖的合作伙伴",
  "address": "商业街123号",
  "description": "我们提供优质服务",
  "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: '来自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': '来自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以禁用通配符解析
• 重要提示：当通过管道将curl输出传递给jq或其他命令时，某些Shell环境中可能无法正确展开环境变量，例如$MATON_API_KEY。使用管道时可能会遇到"无效API密钥"错误。

错误处理

WhatsApp常见错误代码：

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

故障排除：API密钥问题

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

echo $MATON_API_KEY

2. 通过列出连接验证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

故障排除：无效的应用名称

1. 请确保您的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

资源

• WhatsApp Business API 概述
• 发送消息
• 消息模板
• 媒体
• 电话号码
• 商业资料
• Webhooks
• 错误代码
• Maton社区
• Maton支持