WhatsApp API 文档

WhatsApp REST API 的完整参考。认证、端点、webhooks、错误代码和代码示例。

认证

所有 API 请求都需要在 Authorization 请求头中携带 API 密钥。您的 API 密钥在创建实例时生成，可以在仪表盘中找到。

Authorization: Bearer YOUR_API_KEY

未携带有效 API 密钥的请求会返回 401 Unauthorized 错误。API 密钥按实例划分作用域——每个实例都有自己的密钥。

基础 URL

https://api2whats.com

所有端点都相对于此基础 URL。请仅使用 HTTPS——HTTP 请求会被拒绝。

发送文本消息

向 WhatsApp 号码发送文本消息。

POST /send-text

请求体：

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

参数：

• to（字符串，必填）——收件人电话号码，带国家代码，不含 + 或空格
• message（字符串，必填）——文本内容，支持 Unicode 和表情符号

响应：

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

发送图片

通过 URL 或 Base64 发送图片。

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

参数：

• to（字符串，必填）——收件人电话号码
• image（字符串，必填）——图片 URL 或 Base64 编码的字符串
• caption（字符串，可选）——图片下方的文字说明

发送视频

发送视频文件。

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

发送音频

发送音频文件（语音消息或音频片段）。

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

发送贴纸

发送贴纸图片（WebP 或 PNG 格式）。

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

发送文档

发送文件附件（PDF、DOCX、XLSX 等）。

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

参数：

• to（字符串，必填）——收件人电话号码
• document（字符串，必填）——文档 URL 或 Base64 编码的字符串
• filename（字符串，可选）——显示的文件名（默认为 URL 中的文件名）

发送位置

发送地理位置标记。

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Webhook 配置

Webhooks 让您的服务器实时接收传入消息。通过 API 设置您的 webhook URL：

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

当有人向您已连接的号码发送消息时，API 会向您的 URL 发送 POST 请求：

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

使用每个请求都附带的 X-Signature 请求头验证传入的 webhooks。

实例管理

检查您的 WhatsApp 实例的连接状态：

GET /instance/status

响应：
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

错误代码

速率限制

速率限制因方案而异：

• Basic — 100 次请求/分钟
• Professional — 300 次请求/分钟
• Enterprise — 1000 次请求/分钟

受到速率限制时，API 会返回 429 Too Many Requests，并附带 Retry-After 请求头，告知您可以何时重试。

代码示例

PHP、Python、JavaScript 和 cURL 的可运行示例见我们的代码示例部分。每个示例都是完整、可直接运行的脚本。

分页与限制

列出资源（实例、消息历史）时，API 支持通过查询参数分页：

GET /messages?page=1&limit=50

响应：
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

默认每页大小为 50，最大为 100。使用 page 和 limit 查询参数浏览结果。

批量发送

在单个 API 调用中向多个收件人发送消息。这比为每个收件人单独发起请求更高效。

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

批量发送会自动应用速率限制。响应中包含每条消息的状态，让您知道哪些消息成功、哪些失败。

媒体上传指南

发送媒体时，请遵循以下指南以获得最佳送达效果：

• Images — JPEG 或 PNG，通过 Base64 最大 5MB，通过 URL 可更大。推荐尺寸：横图 1200x630，方图 600x600。
• Videos — MP4 格式，最大 16MB。推荐使用 H.264 编码以获得最佳兼容性。
• Documents — PDF、DOCX、XLSX、PPTX、TXT。通过 URL 最大 100MB。
• Audio — MP3 或 OGG 格式。最大 16MB。
• Stickers — WebP 或 PNG，512x512 像素，最大 500KB。
• Locations — 纬度/经度坐标，可附带名称和地址。

对于 Base64 编码，请包含 data URI 前缀：data:image/jpeg;base64,/9j/4AAQ...。对于 URL，请确保 URL 可公开访问并返回正确的 Content-Type 请求头。

环境变量

将您的 API 密钥和配置存储在环境变量中，而不是代码中：

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

切勿将 .env 文件提交到版本控制。将其添加到 .gitignore。生产环境请使用部署平台的环境变量设置。

版本管理

API 通过 URL 路径进行版本管理。当前版本为 v1（默认版本）。当我们引入破坏性变更时，会发布新版本，并将旧版本至少维护 12 个月。

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

更新日志

我们为所有 API 变更维护公开的更新日志。订阅更新日志的 RSS 订阅源，或在 GitHub 上关注我们以获取最新动态。重大变更会在部署前至少 30 天通过邮件通知所有注册用户。

需要帮助？

请查看常见问题中的常见疑问。如有具体问题，请联系我们的支持团队。我们会在 24 小时内回复。

常见问题

消息的最大长度是多少？

文本消息最多支持 4,096 个字符。对于更长的内容，请考虑发送文档或将消息拆分多次发送。

我可以向群组发送消息吗？

目前 API 仅支持一对一消息。群组消息已在我们的路线图中，将在未来版本提供。

消息送达速度有多快？

大多数消息会在 1-3 秒内送达。送达时间取决于收件人的网络连接和设备状态。发送给离线设备的消息会由 WhatsApp 排队，待设备上线后送达。

有免费额度吗？

您可以免费创建账号并浏览仪表盘。付费方案每月 9.99 美元起，即可使用 API 访问和消息发送。如需试用，请联系我们。

如果我的 API 密钥泄露了怎么办？

请立即从仪表盘吊销泄露的密钥，并生成新密钥。所有使用旧密钥的活动会话都将被终止。我们建议定期轮换 API 密钥，并将其存储在环境变量中。

我可以将 API 用于群发消息吗？

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

状态页

在我们的状态页查看系统状态和历史可用性。我们会在故障期间提供实时更新，并针对任何服务中断发布详细的事后报告。