Отправка SMS через 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(); // идентификатор сообщения обычным текстом

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  # идентификатор сообщения обычным текстом, не 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

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,
)

Как подсчитать сегменты до отправки?

Вызовите 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 и объект bulkListInfo с total, validCount, invalidCount и duplicate. Сохраните bulkSessionId вместе с кампанией. Задачи можно просматривать, приостанавливать, возобновлять и прерывать с помощью эндпоинтов из справочника. Кроме того, перед большой рассылкой можно проверить номера через POST /sms/lookup; см. наше руководство по HLR-запросам.

Как получать статус доставки?

Статусы доставки отправляются на URL вебхука, настроенный в вашем аккаунте. Сообщение проходит через SUBMITTED и SENT к DELIVERED либо завершается как FAILED или REJECTED. Вы сообщаете нашей команде публичный HTTPS URL, а у реселлеров может быть по одному вебхуку на каждый субаккаунт.

Поля payload различаются по каналам, а в спецификации API нет единой схемы вебхука, поэтому сначала логируйте исходное тело и сопоставляйте поля по реальному событию в вашем аккаунте. Минимальный приёмник сохраняет событие и быстро подтверждает получение:

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"
  }'

Подробнее — в руководстве по вебхукам и в материале о статусах доставки сообщений.

Как обрабатывать ошибки и избегать дубликатов?

Сначала обрабатывайте HTTP-статус, затем тело ошибки. Повторяйте только при сетевых ошибках, 429 и 5xx.

Ошибки API возвращаются JSON-телом из пяти полей: status, error, message, errorCode и requestUri. Документированный лимит REST по умолчанию — 200 запросов в секунду на постоянной основе; лимиты вашего аккаунта подтверждаются вместе с учётными данными.

API не принимает ключ идемпотентности. Запрос может выполниться, а ответ потеряться, и тогда слепой повтор отправит сообщение дважды. Перед вызовом запишите строку со статусом pending, ключом которой будет ваш собственный идентификатор операции, сохраните возвращённый идентификатор сообщения, а после тайм-аута проверьте статус по вебхуку, прежде чем отправлять снова. Для массовых отправок задавайте allowDuplicate значение false. Подробности — в разделе ошибки и лимиты.

Пример: коды входа для регионального приложения

«Souq Rafiq» (условный пример), розничный продавец из ОАЭ, отправляет коды входа по SMS.

1. Сервис аутентификации генерирует шестизначный код, сохраняет его хеш со сроком действия пять минут и записывает отправку в статусе pending.
2. Он вызывает /sms/sendSms с messageType=UNICODE для арабскоязычных пользователей и TEXT для англоязычных.
3. При ответе 200 он сохраняет идентификатор сообщения.
4. Обработчик вебхука отмечает запись как DELIVERED, FAILED или REJECTED.
5. Если после короткого ожидания статус не DELIVERED, приложение предлагает повторную отправку и, если настроено, другой канал. См. резервный канал.
6. Ограничения на запросы кода по номеру и по IP защищают от злоупотреблений; см. защиту от SMS pumping.

Какие типичные ошибки?

• Вызов r.json() для ответа на отправку. Это обычный текст.
• Неверные имена полей. Используйте senderId, destinationNumber и message; поля вроде to, from или text в этом эндпоинте не используются.
• Знаки плюс и ведущие нули в номерах.
• Забытый UNICODE для арабского, из-за чего текст искажается.
• Незарегистрированные Sender ID. В некоторых странах их блокируют или заменяют; проверьте правила для вашего направления и попросите нас оформить регистрацию.
• Принятие 200 за доставку.
• Токен в мобильном приложении или браузере, откуда его может извлечь кто угодно.
• Ограничения: в этом руководстве показан типичный запрос. Необязательные поля, например форматы планирования, уточняйте у нашей команды.

Как помогает OmniChannels.ai

OmniChannels.ai отправляет A2P SMS через прямые подключения BroadNet к операторам, с двусторонними SMS, именами отправителей, Unicode и арабским, HLR-запросами и SMPP 3.4 для больших объёмов. REST API на https://api.broadnet.me использует Bearer-токен и охватывает также WhatsApp, RCS и другие каналы, а статусы доставки приводятся к единому формату вебхука. Наша команда вместе с вами готовит регистрацию имён отправителей. См. справочник SMS API или канал SMS.