Обзор
API BroadNet — это REST API по HTTPS. Вы проходите аутентификацию с помощью токена Bearer, отправляете JSON запрос или многокомпонентный запрос на конечную точку канала и получаете в ответ идентификатор сообщения или сводку по пакету. Статус доставки передается на URL-адрес веб-перехватчика, настроенный в вашей учетной записи. Полный API, включающий 329 путей и 376 операций по восьми каналам, опубликован в спецификации OpenAPI 3.1. Примеры на этой странице используют curl, Node.js, Python, Java, C#, Go, Ruby и официальный SDK TypeScript.
Окружающая среда
Примеры кода на этой странице обращаются к базовому URL промышленной среды. Тестовые учётные данные и адрес для отправки тестового трафика вы получите вместе с тестовым доступом: запросите его на /signup, мы ответим в течение одного рабочего дня.
| Среда | Базовый URL |
|---|---|
| Продакшн | https://api.broadnet.me |
Аутентификация
Каждый запрос содержит ваш токен доступа в заголовке HTTP. Токен выдается для каждой учетной записи и поступает из вашей учетной записи BroadNet. В примерах на этой странице он считывается из переменной среды с именем BROADNET_TOKEN.
Authorization: Bearer $BROADNET_TOKENЕсли токен отсутствует или недействителен, API отвечает HTTP 401 и JSON сообщением об ошибке в стандартном формате, описанном ниже. Нет вызовов, которые бы обменивали имя пользователя и пароль на токен.
Отправить SMS
Отправьте одно SMS-сообщение с JSON телом. Четыре обязательных поля: отправитель, получатель, текст и кодировка.
Обязательные поля
| Поле | Тип данных | Описание |
|---|---|---|
| senderId | string | Ваш утвержденный идентификатор отправителя, отображаемый получателю как отправитель. |
| destinationNumber | string | Номер получателя с кодом страны, только цифры, без знака плюс. |
| message | string | Текст сообщения. |
| messageType | string | Кодировка: TEXT для текста GSM-7, UNICODE для арабского языка, эмодзи и других шрифтов. |
Необязательные поля
| Поле | Тип данных | Описание |
|---|---|---|
| charCount | integer | Количество символов, возвращаемое функцией /sms/identify. |
| smsParts | integer | Количество сегментов, возвращаемое функцией /sms/identify. |
| charLimit | integer | Количество символов в сегменте, возвращаемое функцией /sms/identify. |
| expiryHour | integer | Срок действия указан в часах. |
| isSchedule | boolean | Установите значение true, чтобы отправить сообщение по расписанию, а не сейчас. |
| delay | number | Перед отправкой сделайте паузу. |
| gmt | string | Для планирования использовалось смещение по Гринвичу. |
| time | — | Запланированное время отправки (с помощью isSchedule). |
| repeat | — | Повторить настройку для запланированных отправок. |
| peId | string | Идентификатор основного субъекта, если это требуется регулирующим органом. |
| templateId | string | Зарегистрированный идентификатор шаблона, если он требуется регулирующим органом. |
| telemarketerId | string | Идентификатор телемаркетера, если это требуется регулирующим органом. |
| campaignName | string | Ваша метка для сообщения о проблеме. |
curl -X POST https://api.broadnet.me/sms/sendSms \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}'
# 200 OK → response body is the message ID, e.g. 2603121407537573731// 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: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
}),
});
console.log(await res.text()); // message IDimport os, requests
r = requests.post(
"https://api.broadnet.me/sms/sendSms",
headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
json={
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT",
},
)
print(r.status_code, r.text) # message ID// Java 11+ — java.net.http is built in, nothing to install
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendSms {
public static void main(String[] args) throws Exception {
String json = "{"
+ "\"senderId\": \"BroadNet\", "
+ "\"destinationNumber\": \"447700900123\", "
+ "\"message\": \"Your verification code is 482913\", "
+ "\"messageType\": \"TEXT\""
+ "}";
HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.broadnet.me/sms/sendSms"))
.header("Authorization", "Bearer " + System.getenv("BROADNET_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.statusCode() + " " + res.body()); // 200 + message ID
}
}// .NET 6+ console app (Program.cs) — HttpClient is built in, no NuGet package
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("BROADNET_TOKEN"));
// PostAsJsonAsync sends Content-Type: application/json
var res = await http.PostAsJsonAsync("https://api.broadnet.me/sms/sendSms", new
{
senderId = "BroadNet",
destinationNumber = "447700900123",
message = "Your verification code is 482913",
messageType = "TEXT",
});
var id = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode} {id}"); // 200 + message IDpackage main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body := []byte(`{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}`)
req, err := http.NewRequest(http.MethodPost, "https://api.broadnet.me/sms/sendSms", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BROADNET_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
id, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(id)) // 200 + message ID
}require "net/http"
require "json"
uri = URI("https://api.broadnet.me/sms/sendSms")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('BROADNET_TOKEN')}"
req["Content-Type"] = "application/json"
req.body = {
senderId: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts "#{res.code} #{res.body}" # 200 + message ID// npm install @broadnet/cpaas-sdk axios
import { Configuration, SMSSMSApi } from "@broadnet/cpaas-sdk";
const sms = new SMSSMSApi(
new Configuration({
basePath: "https://api.broadnet.me",
accessToken: process.env.BROADNET_TOKEN!,
}),
);
const res = await sms.smsSendsmsPost({
sMSSmsRequest: {
senderId: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
},
});
console.log(res.data); // message IDВ случае успешного выполнения запроса возвращается HTTP 200 и идентификатор сообщения в качестве тела ответа, без JSON конверта:
HTTP/1.1 200 OK
2603121407537573731Кодирование и сегменты
Поле messageType задает кодировку, а кодировка определяет количество символов, помещающихся в один сегмент SMS-сообщения. Более длинные сообщения разбиваются на сегменты и собираются заново на телефоне.
| messageType | Одно SMS | По сегментам (длинное сообщение) | Использовать для |
|---|---|---|---|
| TEXT | 160 | 153 | Только символы GSM-7. |
| UNICODE | 70 | 67 | Любая другая письменность: арабский, кириллица, эмодзи, символы с диакритическими знаками, не относящиеся к GSM-7. |
Не уверены, какую кодировку использовать? Обратитесь к API. Конечная точка identify анализирует сообщение и возвращает его кодировку, количество символов, количество сегментов и количество символов в сегменте, которые вы можете передать непосредственно в запрос на отправку.
curl -X POST https://api.broadnet.me/sms/identify \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "message": "Your verification code is 482913" }'{
"message": "Your verification code is 482913",
"messageType": "TEXT",
"smscount": 1,
"charCount": 32,
"charLimit": 160
}Попробуйте сделать это без написания кода. счетчик символов SMS.
Форматы телефонных номеров
Номера назначения состоят из кода страны, за которым следует национальный номер, только в цифрах. Не добавляйте знак плюса в начале, префикс 00, пробелы, дефисы или скобки.
| Пример | Результат | Почему |
|---|---|---|
| 447700900123 | Действительный | Код страны 44 плюс национальный номер, только цифры. |
| +44 7700 900123 | Отклонять | Содержит знак плюса и пробелы. Сначала удалите их. |
| 07700900123 | Отклонять | Национальный формат с ведущим нулем и без кода страны. |
Массовая рассылка SMS
Чтобы отправить одно сообщение нескольким получателям, загрузите файл с номерами в многокомпонентном запросе. Запрос состоит из двух частей. Первая, destinationNumberFile, представляет собой CSV- или TXT-файл с номерами. Вторая, bulkRequest, — это JSON строка, содержащая отправителя, текст, кодировку и название кампании.
curl -X POST https://api.broadnet.me/sms/sendbulk \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-F destinationNumberFile=@recipients.csv \
-F 'bulkRequest={"senderId":"BroadNet","message":"Your statement is ready","messageType":"TEXT","campaignName":"statements"}'{
"status": "success",
"bulkSessionId": "1_20260228105000887",
"credits": "9966465.42850",
"deductcredits": "0.60000",
"bulkListInfo": {
"total": 4,
"validCount": 3,
"invalidCount": 0,
"duplicate": 1
}
}Объект bulkListInfo показывает, сколько чисел было принято, сколько оказалось недействительным и сколько являлось дубликатами. После запуска задания вы можете управлять им по идентификатору пакета:
| Метод HTTP | Путь к конечной точке | Описание |
|---|---|---|
| GET | /sms/list | Отобразите список ваших массовых заданий с указанием количества обработанных и ожидающих обработки. |
| GET | /sms/pause?batch_Id=… | Приостановите выполнение запущенной задачи. |
| GET | /sms/resume?batch_Id=… | Возобновить приостановленное задание. |
| DELETE | /sms/abort?batch_Id=… | Прервать выполнение задания; ожидающие сообщения не отправляются. |
| POST | /sms/resend | Повторно отправьте сообщения из предыдущего задания. |
| POST | /sms/send-now | Немедленно запустите запланированное задание. |
| POST | /sms/auto-schedule | Запланируйте автоматическое выполнение пакетного задания. |
# List your bulk jobs (each entry's id is the batch_Id below)
curl https://api.broadnet.me/sms/list \
-H "Authorization: Bearer $BROADNET_TOKEN"
# Pause, then resume, a running job
curl "https://api.broadnet.me/sms/pause?batch_Id=1024" \
-H "Authorization: Bearer $BROADNET_TOKEN"
curl "https://api.broadnet.me/sms/resume?batch_Id=1024" \
-H "Authorization: Bearer $BROADNET_TOKEN"Поиск номера
Перед отправкой проверьте статус номера (HLR и MNP), например, для очистки списка или обработки перенесенных номеров. Передайте номер в качестве параметра запроса destinationNumber. Необязательный параметр reqType выбирает тип поиска.
curl -X POST "https://api.broadnet.me/sms/lookup?destinationNumber=447700900123" \
-H "Authorization: Bearer $BROADNET_TOKEN"Статус доставки
Статус доставки передается на URL-адрес веб-перехватчика, настроенный в вашей учетной записи BroadNet, по мере прохождения каждым сообщением своего жизненного цикла. Статусы сообщений следуют этому жизненному циклу:
SUBMITTED· Сообщение принято BroadNet и поставлено в очередь для передачи в сеть.SENT· Передано оператору или каналу.DELIVERED· Подтверждено на телефоне.READ· Открыто получателем в каналах, где сообщается о прочтении, например, WhatsApp.FAILED / REJECTED· Не доставлено.
Вы также можете запрашивать статус. Для WhatsApp конечная точка bulk-insights возвращает статус каждого получателя в пакете. Для массовых рассылок SMS конечная точка list возвращает количество обработанных и ожидающих обработки сообщений.
Ошибки
Отсутствующий или недействительный токен Bearer отклоняется на шлюзе API до того, как запрос достигнет API. Шлюз возвращает HTTP 401 с телом JSON, содержащим два поля: error и message:
{
"error": "Unauthorized",
"message": "Missing Authorization token"
}Ошибки, возникающие непосредственно в API, например, ошибка проверки 400, возвращают JSON объект под названием ExceptionResponse, содержащий пять полей: status, error, message, errorCode и requestUri. Приведенные ниже значения являются заполнителями.
{
"status": 400,
"error": "Bad Request",
"message": "…",
"errorCode": "…",
"requestUri": "/sms/sendSms"
}| Статус | Значение |
|---|---|
| 200 | Успех. |
| 400 | Неверный запрос: ошибка валидации или отсутствие обязательного поля. |
| 401 | Отсутствует или недействителен токен Bearer. |
| 403 | Токен действителен, но для вызова этой операции его использование запрещено. |
| 500 | Непредвиденная ошибка сервера. Повторите попытку позже с задержкой. |
Повторная попытка выполняется только при сетевых ошибках и ответах с кодом 5xx, с экспоненциальной задержкой. Исправление ошибок с кодом 4xx вместо повторной попытки. Если ваша учетная запись также использует протокол SMPP, то при отправке данных через него возвращаются стандартные коды состояния SMPP, перечисленные в Руководство по протоколу SMPP.
Другие каналы связи
Один и тот же токен и базовый URL-адрес работают для всех каналов. Это конечные точки отправки; спецификация OpenAPI описывает их поля и связанные с ними конечные точки управления (шаблоны, контакты, отчеты).
| Канал обмена сообщениями | Метод HTTP | Путь к конечной точке | Описание |
|---|---|---|---|
| SMS | POST | /sms/sendSms | Одно сообщение (JSON). |
| SMS | POST | /sms/sendbulk | Массовая загрузка из файла (многокомпонентная). |
| POST | /whatsapp/message/sendbulk | Текст, медиафайлы, шаблоны, интерактивные элементы (многокомпонентные). | |
| RCS | POST | /rcs/message/sendbulk | Сообщения RCS (многокомпонентные). |
| Telegram | POST | /telegram-sms/send | Сообщения в Telegram. |
| POST | /email/email-service/send | Электронное письмо с темой, текстом и получателями. | |
| Messenger | POST | /messenger/message/sendbulk | Сообщения в Facebook Messenger (многокомпонентные). |
| POST | /instagram/message/sendbulk | Сообщения в Instagram (многокомпонентные). | |
| Push | POST | /push/message/send | Push-уведомления (JSON). |
Шаблон отправки в WhatsApp, например:
curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-F batchId=0 \
-F campaignName=order-updates \
-F destinationNo=447700900123 \
-F messageType=TEMPLATE \
-F templateName=order_update \
-F templateLanguage=en_US \
-F bodyTemplateVariables=INV-400Установите batchId равным 0, чтобы запустить новую партию. Поле destinationNo принимает несколько чисел, разделенных запятыми. В ответе содержится идентификатор партии, который вы используете для чтения статуса каждого получателя.
SDK TypeScript
BroadNet выпускает один официальный SDK для TypeScript и Node.js : @broadnet/cpaas-sdk Доступен в npm. Создан на основе спецификации BroadNet OpenAPI, включает модули CommonJS и ES с полными определениями типов и имеет функцию «один класс API на каждый канал». Единственная зависимость времени выполнения — axios; npm устанавливает её вместе с пакетом.
npm install @broadnet/cpaas-sdk axiosimport { Configuration, WhatsAppWhatsAppMessagingAPIApi } from "@broadnet/cpaas-sdk";
const wa = new WhatsAppWhatsAppMessagingAPIApi(
new Configuration({
basePath: "https://api.broadnet.me",
accessToken: process.env.BROADNET_TOKEN!,
}),
);
const res = await wa.whatsappMessageSendbulkPost({
campaignName: "order-updates",
messageType: "TEXT",
destinationNo: "447700900123",
content: "Your order has shipped.",
});
console.log(res.data); // batchId + per-file acceptance countsДля любого другого языка можно напрямую вызвать REST API (в приведенных выше примерах для Node.js, Python, Java, C#, Go и Ruby библиотека BroadNet не используется) или сгенерировать клиент на основе спецификации OpenAPI.
Спецификация OpenAPI
Полный API описан в одном файле OpenAPI 3.1: 329 путей и 376 операций по восьми каналам. Это общедоступная копия спецификации, из которой удалены внутренние примеры. Импортируйте её в Postman или Insomnia, просмотрите в Swagger UI или сгенерируйте клиент.
curl -O https://www.broadnet.me/developers/openapi.yaml
# Generate a client in any language, e.g. Python
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml -g python -o broadnet-pythonПредпочитаете Postman? Импортируйте спецификацию, чтобы получить все операции, или начните с небольшого набора основных вызовов.
Устаревший HTTP API (/websmpp)
Для учетных записей, созданных на платформе BroadNet времен SMPP, можно использовать устаревший HTTP API по пути /websmpp. Он продолжает работать для существующих интеграций и описан в спецификации OpenAPI. В качестве параметров запроса он принимает учетные данные (имя пользователя и пароль или ключ доступа) вместо токена Bearer. Для новых интеграций следует использовать описанный выше REST API.
| Метод HTTP | Путь к конечной точке | Описание |
|---|---|---|
| GET | /websmpp/websms | Отправьте SMS. Добавьте время и смещение по Гринвичу, чтобы запланировать отправку.user, pass (or accesskey), sid, mno, type, text, schtime, gmt |
| POST | /websmpp/json/sms | Отправьте сообщение, используя JSON объект кампании, содержащий учетные данные, отправителя, цифры и текст.campaign { username, password, sender, gsm, text, type } |
| GET | /websmpp/websmsstatus | Статус отправленного сообщения, определяемый по идентификатору ответа.respid, format |
| POST | /websmpp/api/dlrreport | Отчет о доставке за определенный период времени в виде электронной таблицы.username, pass, from_date, to_date |
| GET | /websmpp/hlr/lookup | Поиск HLR для одного числа.username, password, destination |
# Legacy HTTP API — credentials as query parameters (existing integrations only)
curl "https://api.broadnet.me/websmpp/websms?user=USERNAME&pass=PASSWORD&sid=BroadNet&mno=447700900123&type=1&text=Hello"
# Status of a submitted message
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=MESSAGE_ID&format=json"Часто задаваемые вопросы
Как мне пройти аутентификацию?
Отправляйте свой токен доступа в заголовке Authorization: Bearer в каждом запросе. Токен поступает из вашей учетной записи BroadNet ; в API нет вызова для создания токена. Отсутствующий или недействительный токен отклоняется на шлюзе API с HTTP 401 и телом JSON, содержащим два поля: error и message. Храните токен в переменной среды или менеджере секретов, никогда не в системе контроля версий или клиентском коде.
Какой базовый URL используется?
Каждый пример обращается к промышленной среде https://api.broadnet.me. Тестовые учётные данные и адрес для отправки тестового трафика вы получите вместе с тестовым доступом: запросите его на /signup, мы ответим в течение одного рабочего дня.
Как отправить текст на арабском языке или в другом формате Unicode?
Установите messageType в значение UNICODE. Используйте TEXT только в том случае, если каждый символ входит в алфавит GSM-7. Если вы не уверены, вызовите POST /sms/identify с сообщением: он вернет messageType, количество символов, количество сегментов и количество символов в сегменте.
Что возвращает успешная отправка?
POST /sms/sendSms возвращает HTTP 200 и идентификатор сообщения в теле ответа. Массовые отправки возвращают JSON-объект с полями status, bulkSessionId, credits, deductcredits и bulkListInfo.
Как отправить SMS-сообщение нескольким получателям?
Используйте POST /sms/sendbulk с многокомпонентной загрузкой: destinationNumberFile — это CSV или TXT файл с номерами, а bulkRequest — это строка JSON, содержащая senderId, message, messageType и campaignName. Затем задания можно просматривать, приостанавливать, возобновлять или прерывать по идентификатору пакета.
Как узнать статус доставки?
Статус доставки передается на URL-адрес веб-перехватчика, настроенный в вашей учетной записи. Для WhatsApp статус каждого получателя также можно прочитать в /whatsapp/message/bulk-insights.
Существует ли SDK ?
Да, один из них: официальный SDK TypeScript / Node.js, @broadnet/cpaas-sdk на npm, сгенерированный на основе спецификации BroadNet OpenAPI. Для любого другого языка используйте REST API напрямую или сгенерируйте клиент на основе спецификации OpenAPI 3.1 по адресу /developers/openapi.yaml.
Что такое API /websmpp?
Устаревший HTTP API, сохраненный для существующих интеграций эпохи SMPP. Он принимает учетные данные в качестве параметров запроса. Для новых интеграций следует использовать REST API Bearer-token, описанный на этой странице.