Enviar SMS por API: exemplos em Python, Node.js, PHP e 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 nativo)
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 da mensagem em texto simples

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 da mensagem em texto simples, não 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,
)

Como contar segmentos antes de enviar?

Chame POST /sms/identify com a mensagem. Ele devolve a codificação detectada, a contagem de caracteres, a contagem de segmentos e o limite 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
}

Você pode passar smsParts (de smscount), charCount e charLimit em uma requisição de envio. O texto GSM-7 pode aparecer rotulado como GSM-7 na resposta; envie-o como TEXT.

Como envio para muitos números?

Use POST /sms/sendbulk, uma requisição multipart/form-data com um arquivo de destinatários e uma string JSON de configurações.

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

A resposta inclui bulkSessionId e um objeto bulkListInfo com total, validCount, invalidCount e duplicate. Guarde o bulkSessionId com a campanha. Os jobs podem ser listados, pausados, retomados e abortados com os endpoints da referência. Você também pode verificar números antes de um envio grande com POST /sms/lookup; veja nosso guia de consulta HLR.

Como recebo o status de entrega?

Os status de entrega são enviados por push para a URL de webhook configurada na sua conta. Uma mensagem passa por SUBMITTED e SENT até DELIVERED ou termina como FAILED ou REJECTED. Você informa à nossa equipe a URL HTTPS pública, e os revendedores podem ter um webhook por subconta.

Os campos do payload variam por canal, e a especificação da API não define um único esquema de webhook, então registre primeiro o corpo bruto e mapeie os campos a partir de um evento real da sua conta. Um receptor mínimo armazena o evento e confirma rapidamente:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // seu armazenamento; processe de forma assíncrona
  res.sendStatus(200);             // confirme rápido
});

app.listen(3000);

Torne o processamento idempotente, porque o mesmo status pode chegar duas vezes, e nunca deixe um SENT tardio sobrescrever um DELIVERED já armazenado. Se o seu endpoint estava fora do ar, POST /sms/resendDlr reenvia os relatórios de um intervalo de datas:

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

Leia mais no guia de webhooks e em status de entrega de mensagens explicados.

Como tratar erros e evitar duplicatas?

Trate primeiro o status HTTP e depois o corpo do erro. Tente de novo apenas em erros de rede, 429 e 5xx.

Os erros gerados pela API usam um corpo JSON de cinco campos, com status, error, message, errorCode e requestUri. O limite REST padrão documentado é de 200 requisições por segundo de forma sustentada; os limites da sua conta são confirmados junto com as suas credenciais.

A API não aceita chave de idempotência. Uma requisição pode ter sucesso enquanto a resposta se perde, e uma nova tentativa às cegas então envia duas vezes. Grave uma linha pendente, com a sua própria chave de operação, antes de chamar, guarde o ID da mensagem devolvido e, após um timeout, verifique se há um status por webhook antes de enviar de novo. Em envios em massa, defina allowDuplicate como false. Os detalhes estão em Erros e limites.

Exemplo prático: códigos de login para um app regional

A "Souq Rafiq" (sintética), uma varejista dos Emirados Árabes Unidos, envia códigos de login por SMS.

1. O serviço de autenticação gera um código de seis dígitos, guarda um hash com expiração de cinco minutos e grava uma linha de envio pending.
2. Ele chama /sms/sendSms com messageType=UNICODE para usuários de árabe e TEXT para usuários de inglês.
3. Em um 200, guarda o ID da mensagem.
4. O handler do webhook marca a linha como DELIVERED, FAILED ou REJECTED.
5. Se o status não for DELIVERED após uma curta espera, o app oferece um reenvio e, se configurado, outro canal. Veja fallback entre canais.
6. Limites de taxa para solicitações de código por número e por IP protegem contra abusos; veja prevenção de SMS pumping.

Quais são os erros comuns?

• Chamar r.json() na resposta do envio. Ela é texto simples.
• Nomes de campos errados. Use senderId, destinationNumber e message; campos como to, from ou text não fazem parte deste endpoint.
• Sinais de mais e zeros à esquerda nos números.
• Esquecer o UNICODE no árabe, o que corrompe o texto.
• Sender IDs não registrados. Alguns países os bloqueiam ou substituem; confira as regras de sender ID do seu destino e peça que cuidemos do registro.
• Tratar o 200 como entregue.
• Token em um app móvel ou no navegador, onde qualquer pessoa pode extraí-lo.
• Limites: este guia mostra a requisição comum. Campos opcionais, como os formatos de agendamento, devem ser confirmados com a nossa equipe.

Como a OmniChannels.ai ajuda

A OmniChannels.ai envia SMS A2P pela conectividade direta com operadoras da BroadNet, com SMS bidirecional, sender IDs, Unicode e árabe, consulta HLR e SMPP 3.4 para alto volume. A API REST em https://api.broadnet.me usa um token Bearer e também cobre WhatsApp, RCS e outros canais, com status de entrega normalizados em um único formato de webhook. Nossa equipe prepara com você os registros de sender ID. Veja a referência da API de SMS ou o canal de SMS.