WhatsApp消息API发送示例：cURL、Node、Python、PHP

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

// Node.js 18+（内置fetch和FormData）
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("destinationNo", "971500000000");
form.append("messageType", "TEMPLATE");
form.append("templateName", "order_update");
form.append("templateLanguage", "en_US");
form.append("bodyTemplateVariables", "INV-400");

const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // fetch会自动设置multipart边界
  body: form,
});
console.log(await res.json());

import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "destinationNo": "971500000000",
    "messageType": "TEMPLATE",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "bodyTemplateVariables": "INV-400",
}
# 把每个字段作为multipart部分发送（files=），而不是URL编码（data=）。
r = requests.post(
    "https://api.broadnet.me/whatsapp/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())

<?php
$ch = curl_init("https://api.broadnet.me/whatsapp/message/sendbulk");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")],
    // 传入数组（而不是字符串）会让cURL发送multipart/form-data。
    CURLOPT_POSTFIELDS => [
        "batchId" => "0",
        "campaignName" => "order-updates",
        "destinationNo" => "971500000000",
        "messageType" => "TEMPLATE",
        "templateName" => "order_update",
        "templateLanguage" => "en_US",
        "bodyTemplateVariables" => "INV-400",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

{
  "totalFiles": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalDuplicates": 0,
  "batchId": "2609091405000000001",
  "fileResults": [
    {
      "fileName": "direct",
      "totalRecords": 1,
      "successCount": 1,
      "failedRecipients": [],
      "duplicateRecipients": []
    }
  ],
  "message": "Messages queued for delivery"
}

哪些请求字段最重要？

哪些字段必填取决于messageType。以下是常用字段。

定时发送使用scheduled、scheduleTime和gmt，delay用于节流发送。完整列表见WhatsApp API参考。

如何发送带按钮或验证码的模板？

把按钮值放进buttonsTemplateVariable。对于带复制验证码按钮的身份验证模板，请在正文字段和按钮字段中都传入验证码。

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=login_code \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=482913 \
  -F buttonsTemplateVariable=482913

这里的login_code是您自己已获批身份验证模板的占位符。对于多个按钮，buttonsTemplateVariable接受JSON数组。请在服务器端生成验证码，带有效期以哈希形式存储，并且绝不要写入日志。我们的验证码指南介绍了一键、零点击和复制验证码的投递方式。

如何在客户服务窗口内回复？

使用会话消息类型。纯文本回复需要messageType=TEXT和content。

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEXT \
  -F campaignName=support \
  -F "content=Your order has shipped. Reply here if you need anything."

如需回复按钮，请发送messageType=INTERACTIVE以及遵循Meta互动消息格式的interactivePayload。

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=INTERACTIVE \
  -F campaignName=support \
  -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}'

要将收到的消息标记为已读，并可选地显示“正在输入”指示，请用JSON调用POST /whatsapp/message/read：

curl -X POST https://api.broadnet.me/whatsapp/message/read \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }'

设计方面的建议，请参阅我们的互动消息指南。

如何跟踪送达？

状态会推送到您账户上配置的Webhook，也可以按批次读取。每个收件人依次经过SUBMITTED、SENT、DELIVERED和READ，或以FAILED或REJECTED结束并附带原因。

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id为必填；status、destination、search、page和size为可选，其中page从零开始。请把轮询作为错过事件时的兜底手段，并按照我们的Webhook指南构建您的接收端。批次还可以通过参考文档中的批次端点暂停、恢复和中止。

需要处理哪些错误？

先看HTTP状态，再看错误响应体。API以五字段的JSON响应体抛出错误，WhatsApp特有的失败则可能来自Meta。

我们的错误码指南说明了常见的Meta错误码。由于没有幂等键，请遵循错误与限制中的重复发送防护步骤：先写入待处理记录，保存返回的batchId，并在超时后先检查状态再重发。

实战示例：订单通知服务

“Souq Rafiq”（虚构）是阿联酋的一家零售商，订单发货时会发送order_update模板。

1. 订单服务写入一行键为order-8842-shipped、状态为pending的记录。
2. 它以模板和作为bodyTemplateVariables的订单号调用sendbulk。
3. 返回200时，它保存batchId，并把该行标记为accepted。
4. Webhook处理程序把该行更新为DELIVERED或READ，或带原因的FAILED。
5. 如果客户回复，客服工具在窗口内使用TEXT会话消息。
6. 夜间任务读取昨日批次的bulk-insights，并对账任何缺失的状态。

常见错误有哪些？

• **发送JSON。**WhatsApp发送端点是multipart；Content-Type: application/json不起作用。
• **Python用data=**而不是files=，会对表单进行URL编码。
• **在窗口之外发送自由格式文本，**会失败。请使用模板。
• **语言代码错误，**例如用en而不是模板的en_US。
• **把200当作已送达。**它只表示已排队。
• **超时后盲目重试，**可能让客户收到两次消息。
• **token出现在客户端代码中。**请仅从后端调用API。
• **局限：**负载细节因模板而异。首次个性化营销活动的变量布局，请与我们的团队确认。

OmniChannels.ai 如何提供帮助

BroadNet是Meta官方的Business Solution Provider，WhatsApp Business API的开通使用Meta Embedded Signup；我们的团队与您一起准备注册，审批仍由Meta决定。REST API配有OpenAPI 3.1规范和TypeScript SDK @broadnet/cpaas-sdk，各渠道的送达状态统一为同一种格式。请从WhatsApp API文档或快速入门开始。