Enviar SMS por API: ejemplos en Python, Node.js, PHP y 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 integrado)
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 del mensaje en texto sin formato

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 del mensaje en texto sin formato, no 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,
)

¿Cómo cuento los segmentos antes de enviar?

Llame a POST /sms/identify con el mensaje. Devuelve la codificación detectada, el número de caracteres, el número de segmentos y el límite por segmento.

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
}

Puede pasar smsParts (a partir de smscount), charCount y charLimit en una petición de envío. El texto GSM-7 puede aparecer etiquetado como GSM-7 en la respuesta; envíelo como TEXT.

¿Cómo envío a muchos números?

Use POST /sms/sendbulk, una petición multipart/form-data con un archivo de destinatarios y una cadena JSON de ajustes.

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

La respuesta incluye bulkSessionId y un objeto bulkListInfo con total, validCount, invalidCount y duplicate. Guarde bulkSessionId con la campaña. Los trabajos pueden listarse, pausarse, reanudarse y abortarse con los endpoints de la referencia. También puede comprobar los números antes de un envío grande con POST /sms/lookup; consulte nuestra guía de HLR lookup.

¿Cómo recibo el estado de entrega?

Los estados de entrega se envían a la URL del webhook configurada en su cuenta. Un mensaje pasa por SUBMITTED y SENT hasta DELIVERED, o termina como FAILED o REJECTED. Usted facilita a nuestro equipo la URL HTTPS pública, y los revendedores pueden tener un webhook por subcuenta.

Los campos de la carga varían según el canal y la especificación de la API no define un único esquema de webhook, así que registre primero el cuerpo sin procesar y asigne los campos a partir de un evento real de su cuenta. Un receptor mínimo guarda el evento y responde con rapidez:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // su almacenamiento; procese de forma asíncrona
  res.sendStatus(200);             // responda rápido
});

app.listen(3000);

Haga que el procesamiento sea idempotente, porque el mismo estado puede llegar dos veces, y no deje nunca que un SENT tardío sobrescriba un DELIVERED guardado. Si su endpoint estuvo caído, POST /sms/resendDlr vuelve a enviar los informes de un intervalo de fechas:

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

Encontrará más información en la guía de webhooks y en estados de entrega de mensajes explicados.

¿Cómo gestiono los errores y evito los duplicados?

Gestione primero el estado HTTP y después el cuerpo del error. Reintente solo los errores de red, 429 y 5xx.

Los errores que genera la API usan un cuerpo JSON de cinco campos con status, error, message, errorCode y requestUri. El límite REST documentado por defecto es de 200 peticiones por segundo sostenidas; los límites de su cuenta se confirman junto con sus credenciales.

La API no acepta ninguna clave de idempotencia. Una petición puede tener éxito aunque se pierda su respuesta, y un reintento a ciegas envía entonces el mensaje dos veces. Escriba una fila pendiente con su propio ID de operación antes de llamar, guarde el ID de mensaje devuelto y, tras un tiempo de espera agotado, compruebe si hay un estado por webhook antes de volver a enviar. En los envíos masivos, establezca allowDuplicate en false. Los detalles están en Errores y límites.

Ejemplo práctico: códigos de inicio de sesión para una app regional

"Souq Rafiq" (ficticia), un comercio de los Emiratos Árabes Unidos, envía códigos de inicio de sesión por SMS.

1. El servicio de autenticación genera un código de seis dígitos, guarda un hash con una caducidad de cinco minutos y escribe una fila de envío pending.
2. Llama a /sms/sendSms con messageType=UNICODE para los usuarios en árabe y TEXT para los usuarios en inglés.
3. Con un 200, guarda el ID del mensaje.
4. El gestor del webhook marca la fila como DELIVERED, FAILED o REJECTED.
5. Si el estado no es DELIVERED tras una breve espera, la app ofrece un reenvío y, si está configurado, otro canal. Consulte el respaldo entre canales.
6. Los límites de solicitudes de código por número y por IP protegen contra los abusos; consulte la prevención del SMS pumping.

¿Cuáles son los errores habituales?

• Llamar a r.json() sobre la respuesta del envío. Es texto sin formato.
• Nombres de campo incorrectos. Use senderId, destinationNumber y message; campos como to, from o text no forman parte de este endpoint.
• Signos más y ceros iniciales en los números.
• Olvidar UNICODE para el árabe, lo que desfigura el texto.
• Sender ID sin registrar. Algunos países los bloquean o los sustituyen; consulte las normas de sender ID de su destino y pídanos que nos encarguemos del registro.
• Tratar un 200 como entregado.
• El token en una app móvil o en un navegador, donde cualquiera puede extraerlo.
• Límites: esta guía muestra la petición habitual. Los campos opcionales, como los formatos de programación, deben confirmarse con nuestro equipo.

Cómo le ayuda OmniChannels.ai

OmniChannels.ai envía SMS A2P mediante la conectividad directa con operadores de BroadNet, con SMS bidireccional, sender ID, Unicode y árabe, HLR lookup y SMPP 3.4 para grandes volúmenes. La API REST en https://api.broadnet.me usa un token Bearer y abarca también WhatsApp, RCS y otros canales, con los estados de entrega normalizados en un único formato de webhook. Nuestro equipo prepara con usted los registros de sender ID. Consulte la referencia de la API de SMS o el canal SMS.