Descripción general
La API BroadNet es una API REST sobre HTTPS. Te autenticas con un token Bearer, envías una solicitud JSON o multipart a un punto final de canal y recibes un ID de mensaje o un resumen del lote. El estado de entrega se envía a la URL del webhook configurada en tu cuenta. La API completa, con 329 rutas y 376 operaciones en ocho canales, se publica como una especificación OpenAPI 3.1. Los ejemplos de esta página utilizan curl, Node.js, Python, Java, C#, Go, Ruby y el SDK oficial TypeScript.
Entornos
Los ejemplos de esta página llaman a la URL base de producción. Las credenciales de prueba, y adónde enviar el tráfico de prueba, llegan con su acceso de prueba: solicítelo en /signup y le respondemos en un día hábil.
| Ambiente | URL base |
|---|---|
| Producción | https://api.broadnet.me |
Autenticación
Cada solicitud incluye tu token de acceso en una cabecera HTTP. El token se emite por cuenta y proviene de tu cuenta BroadNet. Los ejemplos de esta página lo leen desde una variable de entorno llamada BROADNET_TOKEN.
Authorization: Bearer $BROADNET_TOKENSi el token no existe o es inválido, la API responde con HTTP 401 y un cuerpo de error JSON en el formato de error estándar que se describe a continuación. No se realiza ninguna llamada que intercambie un nombre de usuario y una contraseña por un token.
Enviar un SMS
Envía un SMS con un cuerpo JSON. Los cuatro campos obligatorios son el remitente, el destinatario, el texto y la codificación.
Campos obligatorios
| Campo | Tipo de datos | Descripción |
|---|---|---|
| senderId | string | Tu ID de remitente aprobado, que se muestra al destinatario como remitente. |
| destinationNumber | string | Número del destinatario con código de país, solo dígitos, sin signo más. |
| message | string | El texto del mensaje. |
| messageType | string | Codificación: TEXTO para texto GSM-7, UNICODE para árabe, emojis y otros alfabetos. |
Campos opcionales
| Campo | Tipo de datos | Descripción |
|---|---|---|
| charCount | integer | Recuento de caracteres, tal como lo devuelve /sms/identify. |
| smsParts | integer | Número de segmentos, tal como lo devuelve /sms/identify. |
| charLimit | integer | Caracteres por segmento, tal como los devuelve /sms/identify. |
| expiryHour | integer | Periodo de validez en horas. |
| isSchedule | boolean | Establezca este valor en verdadero para programar el mensaje en lugar de enviarlo ahora. |
| delay | number | Retraso antes de enviar. |
| gmt | string | Se utiliza la diferencia horaria con respecto a GMT para la programación. |
| time | — | Hora de envío programada (con isSchedule). |
| repeat | — | Repita la configuración para los envíos programados. |
| peId | string | Identificador de la entidad principal, cuando así lo requiera el organismo regulador. |
| templateId | string | Identificador de plantilla registrada, cuando así lo exija el organismo regulador. |
| telemarketerId | string | Identificación del teleoperador, cuando así lo exija el organismo regulador. |
| campaignName | string | Su etiqueta para reportar. |
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 IDUna llamada exitosa devuelve HTTP 200 y el ID del mensaje como cuerpo de la respuesta, sin sobre JSON :
HTTP/1.1 200 OK
2603121407537573731Codificación y segmentos
El campo messageType define la codificación, y esta, a su vez, determina cuántos caracteres caben en un segmento de SMS. Los mensajes más largos se dividen en segmentos y se vuelven a ensamblar en el terminal.
| messageType | Mensaje único | Por segmento (mensaje largo) | Uso para |
|---|---|---|---|
| TEXT | 160 | 153 | Solo caracteres GSM-7. |
| UNICODE | 70 | 67 | Cualquier otro alfabeto: árabe, cirílico, emoji, caracteres acentuados fuera del GSM-7. |
¿No sabes qué codificación usar? Consulta la API. El endpoint `identify` analiza un mensaje y devuelve su codificación, el número de caracteres, el número de segmentos y los caracteres por segmento, datos que puedes pasar directamente a la solicitud de envío.
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
}Inténtalo sin escribir código en el contador de caracteres SMS.
formatos de números de teléfono
Los números de destino constan del código del país seguido del número nacional, solo en dígitos. No añada signo más, prefijo 00, espacios, guiones ni paréntesis.
| Ejemplo | Resultado | Por qué |
|---|---|---|
| 447700900123 | Válido | Código de país 44 más el número nacional, solo dígitos. |
| +44 7700 900123 | Rechazar | Contiene un signo más y espacios. Elimínalos primero. |
| 07700900123 | Rechazar | Formato nacional con un cero inicial y sin código de país. |
SMS masivos
Para enviar un mensaje a varios destinatarios, cargue un archivo de números en una solicitud de formulario multipart. La solicitud consta de dos partes. La primera, destinationNumberFile, es un archivo CSV o TXT con los números. La segunda, bulkRequest, es una cadena JSON con el remitente, el texto, la codificación y el nombre de la campaña.
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
}
}El objeto bulkListInfo indica cuántos números se aceptaron, cuántos no eran válidos y cuántos eran duplicados. Una vez que se está ejecutando un trabajo, puede gestionarlo mediante su ID de lote:
| Método HTTP | Ruta del punto final | Descripción |
|---|---|---|
| GET | /sms/list | Enumera tus trabajos masivos con la cantidad de trabajos procesados y pendientes. |
| GET | /sms/pause?batch_Id=… | Pausar un trabajo en ejecución. |
| GET | /sms/resume?batch_Id=… | Reanudar un trabajo pausado. |
| DELETE | /sms/abort?batch_Id=… | Se cancela una tarea; los mensajes pendientes no se envían. |
| POST | /sms/resend | Reenviar mensajes de un trabajo anterior. |
| POST | /sms/send-now | Libere una tarea programada de inmediato. |
| POST | /sms/auto-schedule | Programar un trabajo masivo automáticamente. |
# 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"Búsqueda de números
Verifique el estado de un número (HLR y MNP) antes de enviarlo, por ejemplo, para limpiar una lista o gestionar números portados. Pase el número como parámetro de consulta destinationNumber. El parámetro opcional reqType selecciona el tipo de búsqueda.
curl -X POST "https://api.broadnet.me/sms/lookup?destinationNumber=447700900123" \
-H "Authorization: Bearer $BROADNET_TOKEN"Estado de la entrega
El estado de entrega se envía a la URL del webhook configurada en su cuenta BroadNet a medida que cada mensaje avanza en su ciclo de vida. Los estados de los mensajes siguen este ciclo de vida:
SUBMITTED· Aceptado por BroadNet y puesto en cola para la red.SENT· Entregado al operador o canal.DELIVERED· Confirmado en el teléfono.READ· Abierto por el destinatario, en canales que informan lecturas, como WhatsApp.FAILED / REJECTED· No entregado.
También puedes consultar el estado. Para WhatsApp, el punto final bulk-insights devuelve el estado de cada destinatario en un lote. Para los envíos masivos de SMS, el punto final list devuelve el número de mensajes procesados y pendientes.
Errores
Un token Bearer faltante o no válido es rechazado en la pasarela API antes de que la solicitud llegue a la API. La pasarela devuelve HTTP 401 con un cuerpo JSON de dos campos, error y message:
{
"error": "Unauthorized",
"message": "Missing Authorization token"
}Los errores generados por la propia API, como un error de validación 400, devuelven un cuerpo JSON llamado ExceptionResponse, con cinco campos: status, error, message, errorCode y requestUri. Los valores que aparecen a continuación son marcadores de posición.
{
"status": 400,
"error": "Bad Request",
"message": "…",
"errorCode": "…",
"requestUri": "/sms/sendSms"
}| Estado | Significado |
|---|---|
| 200 | Éxito. |
| 400 | Solicitud incorrecta: error de validación o falta un campo obligatorio. |
| 401 | Token Bearer faltante o no válido. |
| 403 | El token es válido, pero no tiene permiso para llamar a esta operación. |
| 500 | Error inesperado del servidor. Inténtalo de nuevo más tarde con un tiempo de espera. |
Reintentar solo en caso de errores de red y respuestas 5xx, con retroceso exponencial. Corregir errores 4xx en lugar de reintentarlos. Si su cuenta también se vincula a través de SMPP, los envíos allí devuelven códigos de estado SMPP estándar, que se enumeran en el Guía del protocolo SMPP.
Otros canales de mensajería
El mismo token y la misma URL base funcionan para todos los canales. Estos son los puntos finales de envío; la especificación OpenAPI documenta sus campos y los puntos finales de administración relacionados (plantillas, contactos, informes).
| Canal de mensajería | Método HTTP | Ruta del punto final | Descripción |
|---|---|---|---|
| SMS | POST | /sms/sendSms | Mensaje único (JSON). |
| SMS | POST | /sms/sendbulk | Procesamiento masivo desde un archivo (multipartes). |
| POST | /whatsapp/message/sendbulk | Texto, multimedia, plantillas, interactivo (multipartes). | |
| RCS | POST | /rcs/message/sendbulk | Mensajes RCS (multipartes). |
| Telegram | POST | /telegram-sms/send | Mensajes de Telegram. |
| POST | /email/email-service/send | Correo electrónico con asunto, cuerpo y destinatarios. | |
| Messenger | POST | /messenger/message/sendbulk | Mensajes de Facebook Messenger (de varias partes). |
| POST | /instagram/message/sendbulk | Mensajes de Instagram (varias partes). | |
| Push | POST | /push/message/send | Notificaciones push (JSON). |
Por ejemplo, una plantilla WhatsApp para enviar:
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-400Establezca batchId en 0 para iniciar un nuevo lote. El campo destinationNo acepta varios números separados por comas. La respuesta incluye el ID del lote que se utiliza para consultar el estado de cada destinatario.
SDK TypeScript
BroadNet publica un SDK oficial para TypeScript y Node.js : @broadnet/cpaas-sdk Disponible en npm. Se genera a partir de la especificación BroadNet OpenAPI, incluye módulos CommonJS y ES con definiciones de tipos completas y cuenta con una clase API por cada canal. Su única dependencia de ejecución es axios, que npm instala junto con él.
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 countsPara cualquier otro idioma, llame directamente a la API REST (los ejemplos de Node.js, Python, Java, C#, Go y Ruby anteriores no utilizan la biblioteca BroadNet) o genere un cliente a partir de la especificación OpenAPI.
Especificación OpenAPI
La API completa se describe en un archivo OpenAPI 3.1: 329 rutas y 376 operaciones en ocho canales. Esta es una copia pública de la especificación, sin ejemplos internos. Puedes importarla a Postman o Insomnia, explorarla en Swagger UI o generar un cliente.
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¿Prefieres Postman? Importa la especificación para obtener todas las operaciones, o comienza con una pequeña colección de las llamadas esenciales.
API HTTP heredada (/websmpp)
Las cuentas que se crearon en la plataforma BroadNet de la era SMPP pueden usar la API HTTP heredada en la ruta /websmpp. Esta API se mantiene activa para las integraciones existentes y está documentada en la especificación OpenAPI. Requiere credenciales como parámetros de solicitud (usuario y contraseña o clave de acceso) en lugar de un token Bearer. Las nuevas integraciones deben usar la API REST descrita anteriormente.
| Método HTTP | Ruta del punto final | Descripción |
|---|---|---|
| GET | /websmpp/websms | Envía un SMS. Añade una hora programada y la diferencia horaria con respecto a GMT para programarlo.user, pass (or accesskey), sid, mno, type, text, schtime, gmt |
| POST | /websmpp/json/sms | Enviar con un objeto de campaña JSON que contenga las credenciales, el remitente, los números y el texto.campaign { username, password, sender, gsm, text, type } |
| GET | /websmpp/websmsstatus | Estado de un mensaje enviado, según su ID de respuesta.respid, format |
| POST | /websmpp/api/dlrreport | Informe de entregas para un rango de fechas, en formato de hoja de cálculo.username, pass, from_date, to_date |
| GET | /websmpp/hlr/lookup | Búsqueda HLR para un número.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"Preguntas frecuentes
¿Cómo me autentico?
Envía tu token de acceso en el encabezado Authorization: Bearer en cada solicitud. El token proviene de tu cuenta BroadNet ; la API no realiza ninguna llamada para generar tokens. Un token faltante o no válido es rechazado en la pasarela de API con HTTP 401 y un cuerpo JSON de dos campos, error y message. Guarda el token en una variable de entorno o en un gestor de secretos; nunca lo incluyas en el control de versiones ni en el código del cliente.
¿Cuál es la URL base?
Cada ejemplo llama a producción, https://api.broadnet.me. Las credenciales de prueba, y adónde enviar el tráfico de prueba, llegan con su acceso de prueba: solicítelo en /signup y le respondemos en un día hábil.
¿Cómo puedo enviar texto en árabe u otro texto Unicode?
Establezca messageType en UNICODE. Use TEXT solo cuando todos los caracteres pertenezcan al alfabeto GSM-7. Si tiene dudas, llame a POST /sms/identify con el mensaje: le devolverá el messageType, el número de caracteres, el número de segmentos y los caracteres por segmento.
¿Qué devuelve un envío exitoso?
POST /sms/sendSms devuelve HTTP 200 y el ID del mensaje como cuerpo de la respuesta. Los envíos masivos devuelven un objeto JSON con status, bulkSessionId, credits, deductcredits y bulkListInfo.
¿Cómo puedo enviar un SMS a varios destinatarios?
Utilice POST /sms/sendbulk con una carga multipart: destinationNumberFile es un archivo CSV o TXT con números y bulkRequest es una cadena JSON con senderId, message, messageType y campaignName. Los trabajos se pueden listar, pausar, reanudar o cancelar por ID de lote.
¿Cómo puedo consultar el estado de mi envío?
El estado de entrega se envía a la URL del webhook configurada en tu cuenta. En el caso de WhatsApp, el estado de cada destinatario también se puede consultar en /whatsapp/message/bulk-insights.
¿Existe un SDK ?
Sí, una: el SDK oficial TypeScript / Node.js, @broadnet/cpaas-sdk en npm, generado a partir de la especificación OpenAPI BroadNet. Para cualquier otro lenguaje, llame directamente a la API REST o genere un cliente a partir de la especificación OpenAPI 3.1 en /developers/openapi.yaml.
¿Qué es la API /websmpp?
La API HTTP heredada, conservada para las integraciones existentes de la era SMPP, acepta credenciales como parámetros de solicitud. Las nuevas integraciones deben usar la API REST de token Bearer documentada en esta página.