面向开发者的 WhatsApp API — 构建、交付、扩展

面向开发者的 WhatsApp API,提供简洁的 REST 端点、Webhook、六种语言的代码示例,以及随项目扩展的基础设施。

const response = await fetch('https://api2whats.com/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '971501234567',
    message: 'Hello from my app!'
  })
});
const data = await response.json();
console.log(data.id); // message ID

为什么开发者选择此 API

大多数 WhatsApp API 解决方案首先面向非技术用户、其次才是开发者。文档稀疏、错误消息无用,您花更多时间与 API 搏斗而非用它构建。我们反其道而行 — 开发者优先,其他其次。

每个端点返回带清晰错误代码的结构化 JSON。每个请求都有可预测的响应格式。文档包含可复制即运行的可工作代码示例。Webhook 系统实时将收到的消息带签名负载推送到您的服务器,以便您验证真实性。

无论您在构建客户支持聊天机器人、订单通知系统、营销自动化工具、或为客户构建定制集成,API 都为您让路,让您专注于代码。

架构概览

API 位于您的应用与 WhatsApp 服务器之间。发送消息时发生以下情况:

1. 您的应用向 API 端点发送 HTTP POST 请求
2. API 使用 Authorization 头中的 API 密钥验证您的请求
3. 消息路由到正确的 WhatsApp 实例(若您有多个)
4. 消息通过持久 WebSocket 连接投递到 WhatsApp
5. 您收到包含消息 ID 和投递状态的响应
6. 后续状态更新(已投递、已读)推送到您的 webhook

整个往返通常耗时不足 50 毫秒。无浏览器、无截图处理、无 DOM 操作。WebSocket 连接持久,自动处理重连、认证刷新和错误恢复。

REST API 参考

所有端点遵循 REST 约定。请求使用 JSON 正文。响应使用 JSON。认证通过 Authorization 头中的 Bearer 令牌。

发送消息

管理实例

Webhook

Webhook 集成

Webhook 是您接收收到消息的方式。当有人向您连接的 WhatsApp 号码发送消息时,API 向您的 webhook URL 发送包含消息数据的 POST 请求。

Webhook 负载如下所示:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help with my order",
    "timestamp": 1691234567,
    "type": "text"
  }
}

您的 webhook 处理器处理这些数据并可触发任何自动化响应。Webhook 系统支持重试逻辑 — 若您的服务器暂时不可用,API 会在放弃前多次重试投递。

为安全起见,所有 webhook 负载包含 X-Signature 头,您可验证它以确保请求确实来自我们的 API 而非第三方。

六种语言的代码示例

我们为每个常用操作提供可工作的代码示例。每个示例是完整可运行的脚本 — 非留您猜测导入、错误处理或配置的片段。

PHP

<?php
$ch = curl_init('https://api2whats.com/send-text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ***',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '971501234567',
        'message' => 'Hello from PHP!',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    'https://api2whats.com/send-text',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'to': '971501234567',
        'message': 'Hello from Python!',
    }
)
print(response.json())

JavaScript (Node.js)

const response = await fetch('https://api2whats.com/send-text', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        to: '971501234567',
        message: 'Hello from Node.js!',
    }),
});
const data = await response.json();
console.log(data);

错误处理

API 使用标准 HTTP 状态码并返回结构化错误响应:

{
    "success": false,
    "error": {
        "code": "INSTANCE_DISCONNECTED",
        "message": "The WhatsApp instance is not connected"
    }
}

常见错误代码包括:

• 401 Unauthorized — 无效或缺失的 API 密钥
• 400 Bad Request — 缺少必填字段或数据无效
• 404 Not Found — 实例或资源不存在
• 429 Too Many Requests — 超出速率限制
• 500 Internal Server Error — 我们端出了问题 (罕见)

Webhook 安全性

每个 webhook 请求包含 X-Signature 头,其中含有请求体的 HMAC-SHA256 签名。您的 webhook 处理器应验证此签名,以确保请求确实来自我们的 API 而非第三方。

// Node.js webhook signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const sig = req.headers['x-signature'];
    const body = JSON.stringify(req.body);

    if (!verifySignature(body, sig, WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // Process the message...
    res.json({ success: true });
});

测试与调试

API 提供多种测试和调试集成的工具:

• 仪表板日志 — 从仪表板实时查看所有 API 请求及其响应
• Webhook 测试端点 — 发送测试 webhook 验证您的处理器工作正常
• 消息状态跟踪 — 按 ID 查询任意消息的状态
• 错误率监控 — 在仪表板随时间跟踪您的 API 错误率

我们建议从连接到您个人号码的测试实例开始。发送测试消息、验证 webhook、检查错误处理,然后再用生产流量上线。

开发者最佳实践

• 安全存储 API 密钥 — 使用环境变量,非硬编码字符串。绝不将 API 密钥提交到版本控制。
• 优雅处理错误 — 对瞬态错误(5xx、网络超时)实现指数退避重试逻辑。
• 验证 webhook 签名 — 绝不信任未验证的 webhook 请求。始终检查 X-Signature 头。
• 使用连接池 — 跨请求复用 HTTP 连接,而非为每次 API 调用创建新连接。
• 监控速率限制 — 检查 X-RateLimit-Remaining 头,接近限制时主动限流。
• 记录一切 — 为调试记录请求/响应对。生产日志中脱敏敏感数据(电话号码、消息内容)。

速率限制

速率限制按 API 密钥执行,随套餐变化。API 触及限制时返回 429 状态码和 Retry-After 头。以下是默认值:

• 基础套餐 — 每分钟 100 次请求
• 专业套餐 — 每分钟 300 次请求
• 企业套餐 — 每分钟 1000 次请求

若您持续触及速率限制,考虑升级套餐或在可能处批量请求。

Webhook 负载格式

收到的消息按消息类型以不同格式到达:

文本消息

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hello!",
    "type": "text",
    "timestamp": 1691234567
  }
}

图片消息

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F7",
    "from": "971501234567",
    "type": "image",
    "caption": "Check this out!",
    "mediaUrl": "https://api2whats.com/media/...",
    "mimeType": "image/jpeg",
    "timestamp": 1691234568
  }
}

状态更新

{
  "event": "status",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "delivered",
    "timestamp": 1691234600
  }
}

状态值包括: sent(已交给 WhatsApp)、delivered(到达设备)、和 read(被收件人打开)。

快速上手

1. 创建账号 (免费,无需信用卡)
2. 从 定价页面
3. 从您的 仪表板
4. 通过二维码或配对码连接您的电话号码
5. 阅读 完整 API 文档
6. 发送您的第一条消息并开始构建

社区与支持

加入我们的开发者社区获取帮助、分享集成、随时了解新功能。我们拥有跨各行业构建 WhatsApp 集成的活跃开发者社区。

• 文档 — 带可工作示例的完整 API 参考
• 代码示例 — PHP、Python、JavaScript 和 cURL 的完整可运行脚本
• 电子邮件支持 — 所有套餐层级 24 小时内响应
• 仪表板日志 — API 请求和 webhook 投递的实时可见性
• 状态页面 — 实时系统状态和事件历史

无论您在构建第一个 WhatsApp 集成还是扩展现有集成,我们的资源和支持团队都在这里帮助您成功。