Inviare SMS via API: esempi in 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 integrato)
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 messaggio come testo semplice

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 messaggio come testo semplice, non 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,
)

Come contare i segmenti prima dell'invio?

Chiamate POST /sms/identify con il messaggio. Restituisce la codifica rilevata, il numero di caratteri, il numero di segmenti e il limite per 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
}

Potete passare smsParts (da smscount), charCount e charLimit in una richiesta di invio. Il testo GSM-7 può essere indicato come GSM-7 nella risposta; inviatelo come TEXT.

Come inviare a molti numeri?

Usate POST /sms/sendbulk, una richiesta multipart/form-data con un file di destinatari e una stringa JSON di impostazioni.

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 risposta include bulkSessionId e un oggetto bulkListInfo con total, validCount, invalidCount e duplicate. Memorizzate bulkSessionId con la campagna. I job possono essere elencati, messi in pausa, ripresi e interrotti con gli endpoint del riferimento. Potete anche controllare i numeri prima di un grande invio con POST /sms/lookup; vedi la nostra guida alla HLR lookup.

Come ricevere lo stato di consegna?

Gli stati di consegna vengono inviati all'URL del webhook configurato sul vostro account. Un messaggio passa da SUBMITTED e SENT a DELIVERED, oppure termina come FAILED o REJECTED. Fornite al nostro team l'URL HTTPS pubblico; i reseller possono avere un webhook per ogni sotto-account.

I campi del payload variano per canale e la specifica dell'API non definisce un unico schema di webhook, quindi registrate prima il corpo grezzo e mappate i campi da un evento reale sul vostro account. Un ricevitore minimo salva l'evento e conferma rapidamente:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // il vostro storage; elaborate in modo asincrono
  res.sendStatus(200);             // confermate subito
});

app.listen(3000);

Rendete l'elaborazione idempotente, perché lo stesso stato può arrivare due volte, e non lasciate mai che un SENT in ritardo sovrascriva un DELIVERED già memorizzato. Se il vostro endpoint era fuori servizio, POST /sms/resendDlr reinvia i rapporti per un intervallo di date:

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

Approfondite nella guida ai webhook e negli stati di consegna dei messaggi spiegati.

Come gestire gli errori ed evitare i duplicati?

Gestite prima lo stato HTTP, poi il corpo dell'errore. Riprovate solo in caso di errori di rete, 429 e 5xx.

Gli errori generati dall'API usano un corpo JSON a cinque campi con status, error, message, errorCode e requestUri. Il limite REST documentato per impostazione predefinita è di 200 richieste al secondo sostenute; i limiti del vostro account vengono confermati insieme alle credenziali.

L'API non accetta una chiave di idempotenza. Una richiesta può riuscire mentre la risposta va persa, e un nuovo tentativo alla cieca invia due volte. Scrivete una riga in sospeso, con chiave un vostro ID di operazione, prima della chiamata, memorizzate l'ID del messaggio restituito e dopo un timeout controllate se c'è uno stato dal webhook prima di inviare di nuovo. Per gli invii massivi impostate allowDuplicate su false. I dettagli sono in Errori e limiti.

Esempio pratico: codici di accesso per un'app regionale

«Souq Rafiq» (nome di fantasia), un rivenditore degli Emirati, invia codici di accesso via SMS.

1. Il servizio di autenticazione genera un codice di sei cifre, memorizza un hash con scadenza di cinque minuti e scrive una riga di invio pending.
2. Chiama /sms/sendSms con messageType=UNICODE per gli utenti arabi e TEXT per quelli inglesi.
3. Con 200 memorizza l'ID del messaggio.
4. Il gestore del webhook segna la riga come DELIVERED, FAILED o REJECTED.
5. Se dopo una breve attesa lo stato non è DELIVERED, l'app propone un nuovo invio e, se configurato, un altro canale. Vedi il fallback tra canali.
6. Limiti sulle richieste di codice per numero e per IP proteggono dagli abusi; vedi la prevenzione dell'SMS pumping.

Quali sono gli errori comuni?

• Chiamare r.json() sulla risposta di invio. È testo semplice.
• Nomi di campo sbagliati. Usate senderId, destinationNumber e message; campi come to, from o text non fanno parte di questo endpoint.
• Segni più e zeri iniziali nei numeri.
• Dimenticare UNICODE per l'arabo, che altera il testo.
• Sender ID non registrati. Alcuni paesi li bloccano o li sostituiscono; verificate le regole sui Sender ID della destinazione e chiedeteci di occuparci della registrazione.
• Considerare 200 come consegnato.
• Token in un'app mobile o nel browser, dove chiunque può estrarlo.
• Limiti: questa guida mostra la richiesta più comune. Campi facoltativi come i formati di programmazione dell'invio vanno confermati con il nostro team.

Come vi aiuta OmniChannels.ai

OmniChannels.ai invia SMS A2P tramite la connettività diretta agli operatori di BroadNet, con SMS bidirezionali, Sender ID, Unicode e arabo, HLR lookup e SMPP 3.4 per i volumi elevati. L'API REST su https://api.broadnet.me usa un Bearer token e copre anche WhatsApp, RCS e altri canali, con gli stati di consegna normalizzati in un unico formato di webhook. Il nostro team prepara con voi le registrazioni dei Sender ID. Consultate il riferimento dell'API SMS o il canale SMS.