短信API发送示例：Python、Node.js、PHP与cURL

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "447700900123",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

// Node.js 18+（内置fetch）
const res = await fetch("https://api.broadnet.me/sms/sendSms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "OmniDemo",
    destinationNumber: "447700900123",
    message: "Your OmniDemo code is 482913",
    messageType: "TEXT",
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const messageId = await res.text(); // 纯文本的消息ID

import os
import requests

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "447700900123",
        "message": "Your OmniDemo code is 482913",
        "messageType": "TEXT",
    },
    timeout=15,
)
r.raise_for_status()
message_id = r.text  # 纯文本的消息ID，不是JSON

<?php
$payload = json_encode([
    "senderId" => "OmniDemo",
    "destinationNumber" => "447700900123",
    "message" => "Your OmniDemo code is 482913",
    "messageType" => "TEXT",
]);

$ch = curl_init("https://api.broadnet.me/sms/sendSms");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BROADNET_TOKEN"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$messageId = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status . " " . $messageId . PHP_EOL;

2603121407537573731

如何发送阿拉伯语、emoji或其他Unicode文本？

将messageType设为UNICODE。任何GSM-7字母表之外的字符，例如阿拉伯字母、emoji、弯引号或破折号，都会让整条消息切换为Unicode。

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "971500000000",
        "message": "رمز التحقق الخاص بك هو 482913",
        "messageType": "UNICODE",
        "campaignName": "login-otp",
    },
    timeout=15,
)

在PHP中，调用json_encode时请使用JSON_UNESCAPED_UNICODE。编码决定分段大小，这是3GPP TS 23.040对短信的定义：

大多数运营商按分段计费，所以较长的阿拉伯语消息比同样长度的拉丁字母消息更贵。请阅读我们的Unicode与阿拉伯语短信指南，并试用短信字符计数器。

发送前如何统计分段数？

使用消息调用POST /sms/identify。它会返回检测到的编码、字符数、分段数和每段上限。

curl -X POST https://api.broadnet.me/sms/identify \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your OmniDemo code is 482913" }'

{
  "message": "Your OmniDemo code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 28,
  "charLimit": 160
}

您可以把smsParts（来自smscount）、charCount和charLimit传入发送请求。GSM-7文本在响应中可能被标记为GSM-7；发送时请使用TEXT。

如何发送给大量号码？

使用POST /sms/sendbulk，这是一个multipart/form-data请求，包含一个收件人文件和一个设置的JSON字符串。

curl -X POST https://api.broadnet.me/sms/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F destinationNumberFile=@recipients.csv \
  -F 'bulkRequest={"senderId":"OmniDemo","message":"Your statement is ready in the app.","messageType":"TEXT","campaignName":"oct-statements","allowDuplicate":false}'

import json
import os
import requests

bulk_request = {
    "senderId": "OmniDemo",
    "message": "Your statement is ready in the app.",
    "messageType": "TEXT",
    "campaignName": "oct-statements",
    "allowDuplicate": False,
}

with open("recipients.csv", "rb") as f:
    r = requests.post(
        "https://api.broadnet.me/sms/sendbulk",
        headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
        files={"destinationNumberFile": ("recipients.csv", f, "text/csv")},
        data={"bulkRequest": json.dumps(bulk_request)},
        timeout=60,
    )
print(r.json())

响应中包含bulkSessionId和一个带有total、validCount、invalidCount和duplicate的bulkListInfo对象。请把bulkSessionId与营销活动一起存储。任务可以通过参考文档中的端点列出、暂停、恢复和中止。您也可以在大批量发送之前，用POST /sms/lookup检查号码；请参阅我们的HLR查询指南。

如何接收送达状态？

送达状态会推送到您账户上配置的Webhook URL。一条消息依次经过SUBMITTED和SENT到达DELIVERED，或者以FAILED或REJECTED结束。您把公开的HTTPS URL提供给我们的团队即可，转售商可以为每个子账户设置一个Webhook。

负载字段因渠道而异，API规范也没有定义单一的Webhook结构，所以请先记录原始请求体，再根据您账户上的真实事件映射字段。一个最简接收端只需保存事件并迅速确认：

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // 您自己的存储；异步处理
  res.sendStatus(200);             // 尽快确认
});

app.listen(3000);

请让处理具备幂等性，因为同一状态可能到达两次，并且绝不要让迟到的SENT覆盖已存储的DELIVERED。如果您的端点曾经宕机，POST /sms/resendDlr可以按日期范围重新推送回执：

curl -X POST https://api.broadnet.me/sms/resendDlr \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-10-09",
    "endDate": "2026-10-10",
    "senderId": "OmniDemo",
    "messageStatus": "DELIVERED"
  }'

更多内容请阅读Webhook指南和消息送达状态详解。

如何处理错误并避免重复发送？

先处理HTTP状态，再看错误响应体。只对网络错误、429和5xx重试。

API抛出的错误使用包含status、error、message、errorCode和requestUri五个字段的JSON响应体。文档中记载的REST默认限制为持续每秒200个请求；您账户的具体限制会随凭证一并确认。

该API不接受幂等键。一个请求可能成功但响应丢失，盲目重试就会发送两次。请在调用之前，先以您自己的操作ID为键写入一条待处理行，保存返回的消息ID，并在超时后先检查Webhook状态，再决定是否重发。批量发送时，请把allowDuplicate设为false。详情见错误与限制。

实战示例：区域应用的登录验证码

“Souq Rafiq”（虚构）是阿联酋的一家零售商，通过短信发送登录验证码。

1. 认证服务生成六位验证码，存储带五分钟有效期的哈希，并写入一条pending发送记录。
2. 它调用/sms/sendSms，阿拉伯语用户使用messageType=UNICODE，英语用户使用TEXT。
3. 返回200时，保存消息ID。
4. Webhook处理程序把该记录标记为DELIVERED、FAILED或REJECTED。
5. 如果短暂等待后状态仍不是DELIVERED，应用会提供重发选项，并在配置的情况下提供另一个渠道。请参阅渠道回退。
6. 按号码和按IP限制验证码请求频率，可防止滥用；请参阅短信泵送防范。

常见错误有哪些？

• **对发送响应调用r.json()。**它是纯文本。
• **字段名错误。**请使用senderId、destinationNumber和message；to、from或text等字段不属于该端点。
• 号码中带有加号和前导零。
• 阿拉伯语**忘记使用UNICODE，**导致文本乱码。
• **未注册的发件人ID。**有些国家会封堵或替换它们；请查看目的地的发件人ID规则，并让我们来办理注册。
• 把200当作已送达。
• **把token放在移动应用或浏览器中，**任何人都能提取。
• **局限：**本指南展示的是常见请求。定时发送格式等可选字段，请与我们的团队确认。

OmniChannels.ai 如何提供帮助

OmniChannels.ai通过BroadNet的运营商直连发送A2P短信，支持双向短信、发件人ID、Unicode和阿拉伯语、HLR查询，并提供用于大批量的SMPP 3.4。位于https://api.broadnet.me的REST API使用Bearer token，同时覆盖WhatsApp、RCS和其他渠道，送达状态统一为一种Webhook格式。我们的团队与您一起准备发件人ID注册。请查看短信API参考或短信渠道。