BroadNet
Guida per gli sviluppatori · API REST·OpenAPI 3.1

L'API BroadNet.

Un'unica API REST per SMS, WhatsApp, RCS, Telegram, email, Messenger, Instagram e notifiche push. Ogni richiesta viene inviata tramite HTTPS e autenticata con un token Bearer. Ogni canale ha il proprio gruppo di percorsi e l'intera API è descritta in una specifica OpenAPI 3.1 scaricabile. Questa pagina illustra le chiamate con cui la maggior parte delle integrazioni inizia, a partire da un singolo SMS.

Tempo di lettura: 12 minuti·Aggiornato a settembre 2026Hub per sviluppatori

Panoramica

L'API BroadNet è API REST su HTTPS. L'autenticazione avviene tramite un token Bearer, si invia una richiesta JSON o multipart a un endpoint di canale e si riceve in risposta un ID del messaggio o un riepilogo del batch. Lo stato di consegna viene inviato all'URL del webhook configurato nell'account. L'API completa, con 329 percorsi e 376 operazioni su otto canali, è pubblicata come specifica OpenAPI 3.1. Gli esempi in questa pagina utilizzano curl, Node.js, Python, Java, C#, Go, Ruby e l'SDK ufficiale TypeScript.

Ambienti

Gli esempi in questa pagina chiamano l'URL di base di produzione. Le credenziali di test, e l'indirizzo a cui inviare il traffico di prova, arrivano con il tuo accesso di test: richiedilo su /signup e rispondiamo entro un giorno lavorativo.

AmbienteURL di base
Produzionehttps://api.broadnet.me

Autenticazione

Ogni richiesta include il tuo token di accesso nell'intestazione HTTP. Il token viene emesso per ogni account e proviene dal tuo account BroadNet. Gli esempi in questa pagina lo leggono da una variabile d'ambiente chiamata BROADNET_TOKEN.

HTTP
Authorization: Bearer $BROADNET_TOKEN

Se il token è mancante o non valido, l'API risponde con HTTP 401 e un corpo di errore JSON nel formato di errore standard descritto di seguito. Non esiste alcuna chiamata che scambi nome utente e password con un token.

Invia un SMS

Invia un SMS con un corpo JSON. I quattro campi obbligatori sono il mittente, il destinatario, il testo e la codifica.

POSThttps://api.broadnet.me/sms/sendSms

Campi obbligatori

CampoTipo di datiDescrizione
senderIdstringIl tuo ID mittente approvato, mostrato al destinatario come mittente.
destinationNumberstringNumero del destinatario con prefisso internazionale, solo cifre, senza segno più.
messagestringIl testo del messaggio.
messageTypestringCodifica: TEXT per testo GSM-7, UNICODE per arabo, emoji e altri alfabeti.

Campi facoltativi

CampoTipo di datiDescrizione
charCountintegerConteggio dei caratteri, come restituito da /sms/identify.
smsPartsintegerNumero di segmenti, come restituito da /sms/identify.
charLimitintegerCaratteri per segmento, come restituito da /sms/identify.
expiryHourintegerPeriodo di validità in ore.
isSchedulebooleanImposta su true per programmare l'invio del messaggio anziché inviarlo immediatamente.
delaynumberAttendere prima dell'invio.
gmtstringOffset GMT utilizzato per la pianificazione.
time—Orario di invio programmato (con isSchedule).
repeat—Impostazione ripetuta per gli invii programmati.
peIdstringIdentificativo dell'entità principale, laddove richiesto da un'autorità di regolamentazione.
templateIdstringID del modello registrato, laddove richiesto da un ente regolatore.
telemarketerIdstringID per operatori di telemarketing, laddove richiesto da un ente regolatore.
campaignNamestringLa tua etichetta per la segnalazione.
curl
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
// 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 ID
Python · requests
import 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
// 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
    }
}
C# · .NET 6+ HttpClient
// .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 ID
Go · net/http
package 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
}
Ruby · Net::HTTP
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
TypeScript SDK · @broadnet/cpaas-sdk
// 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

Una chiamata andata a buon fine restituisce HTTP 200 e l'ID del messaggio come corpo della risposta, senza involucro JSON :

200 OK
HTTP/1.1 200 OK

2603121407537573731

Codifica e segmenti

Il campo messageType imposta la codifica, e la codifica determina quanti caratteri possono essere inseriti in un segmento SMS. I messaggi più lunghi vengono suddivisi in segmenti e riassemblati sul dispositivo mobile.

messageTypeSMS singoloPer segmento (messaggio lungo)Utilizzare per
TEXT160153Solo caratteri GSM-7.
UNICODE7067Qualsiasi altro alfabeto: arabo, cirillico, emoji, caratteri accentati al di fuori dello standard GSM-7.

Non sai quale codifica utilizzare? Chiedi API. L'endpoint identify analizza un messaggio e restituisce la sua codifica, il numero di caratteri, il numero di segmenti e i caratteri per segmento, che puoi passare direttamente alla richiesta send.

curl · /sms/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" }'
200 OK
{
  "message": "Your verification code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 32,
  "charLimit": 160
}

Provalo senza scrivere codice nel contatore di caratteri SMS.

Formati dei numeri di telefono

I numeri di destinazione sono composti dal prefisso internazionale seguito dal numero nazionale, solo cifre. Non aggiungere segni più iniziali, prefissi 00, spazi, trattini o parentesi.

EsempioRisultatoPerché
447700900123ValidoPrefisso internazionale 44 seguito dal numero nazionale, solo cifre.
+44 7700 900123RifiutareContiene un segno più e degli spazi. Rimuovili prima.
07700900123RifiutareFormato nazionale con zero iniziale e senza prefisso internazionale.

SMS di massa

Per inviare un messaggio a più destinatari, carica un file di numeri in una richiesta multipart. La richiesta è composta da due parti. La prima, destinationNumberFile, è un file CSV o TXT contenente i numeri. La seconda, bulkRequest, è una stringa JSON con il mittente, il testo, la codifica e il nome della campagna.

POSThttps://api.broadnet.me/sms/sendbulk
curl · /sms/sendbulk
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"}'
200 OK
{
  "status": "success",
  "bulkSessionId": "1_20260228105000887",
  "credits": "9966465.42850",
  "deductcredits": "0.60000",
  "bulkListInfo": {
    "total": 4,
    "validCount": 3,
    "invalidCount": 0,
    "duplicate": 1
  }
}

L'oggetto bulkListInfo indica quanti numeri sono stati accettati, quanti non validi e quanti duplicati. Una volta avviato un processo, è possibile gestirlo tramite il suo ID batch:

Metodo HTTPPercorso del punto finaleDescrizione
GET/sms/listElenca i tuoi lavori in blocco con il numero di lavori elaborati e in sospeso.
GET/sms/pause?batch_Id=…Metti in pausa un processo in esecuzione.
GET/sms/resume?batch_Id=…Riprendi un lavoro sospeso.
DELETE/sms/abort?batch_Id=…Annulla l'operazione; i messaggi in sospeso non vengono inviati.
POST/sms/resendReinvia i messaggi di un lavoro precedente.
POST/sms/send-nowRilascia immediatamente un'attività pianificata.
POST/sms/auto-schedulePianifica automaticamente un'elaborazione in blocco.
curl · batch control
# 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"

Ricerca del numero

Prima di inviare un numero (HLR e MNP), verificane lo stato (ad esempio per pulire un elenco o per gestire i numeri trasferiti). Passa il numero come parametro di query destinationNumber. Il parametro opzionale reqType seleziona il tipo di ricerca.

POSThttps://api.broadnet.me/sms/lookup
curl · /sms/lookup
curl -X POST "https://api.broadnet.me/sms/lookup?destinationNumber=447700900123" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

Stato della consegna

Lo stato di consegna viene inviato all'URL del webhook configurato nel tuo account BroadNet man mano che ogni messaggio attraversa il suo ciclo di vita. Gli stati dei messaggi seguono questo ciclo di vita:

  • SUBMITTED · Accettato da BroadNet e messo in coda per la rete.
  • SENT · Consegnato all'operatore o al canale.
  • DELIVERED · Confermato sul telefono.
  • READ · Aperto dal destinatario, sui canali che segnalano letture, come WhatsApp.
  • FAILED / REJECTED · Non consegnato.

È anche possibile effettuare un polling per verificare lo stato. Per WhatsApp, l'endpoint bulk-insights restituisce lo stato di ciascun destinatario in un batch. Per le operazioni di invio massivo di SMS, l'endpoint list restituisce il numero di messaggi elaborati e in sospeso.

Errori

Un token Bearer mancante o non valido viene rifiutato dal gateway API prima che la richiesta raggiunga l'API. Il gateway restituisce HTTP 401 con un corpo JSON composto da due campi: error e message.

401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Missing Authorization token"
}

Gli errori generati dall'API stessa, come ad esempio un errore di validazione 400, restituiscono un corpo JSON chiamato ExceptionResponse, con cinque campi: status, error, message, errorCode e requestUri. I valori seguenti sono segnaposto.

400 · ExceptionResponse
{
  "status": 400,
  "error": "Bad Request",
  "message": "…",
  "errorCode": "…",
  "requestUri": "/sms/sendSms"
}
StatoSignificato
200Successo.
400Richiesta non valida: errore di convalida o campo obbligatorio mancante.
401Token Bearer mancante o non valido.
403Il token è valido ma non è autorizzato a richiamare questa operazione.
500Errore imprevisto del server. Riprova più tardi con un intervallo di tempo maggiore.

Riprova solo in caso di errori di rete e risposte 5xx, con backoff esponenziale. Correggi gli errori 4xx invece di riprovarli. Se il tuo account è collegato anche tramite SMPP, gli invii restituiscono codici di stato SMPP standard, elencati nel Guida al protocollo SMPP.

Altri canali di messaggistica

Lo stesso token e lo stesso URL di base funzionano per ogni canale. Questi sono gli endpoint di invio; la specifica OpenAPI documenta i relativi campi e gli endpoint di gestione correlati (modelli, contatti, report).

Canale di messaggisticaMetodo HTTPPercorso del punto finaleDescrizione
SMSPOST/sms/sendSmsMessaggio singolo (JSON).
SMSPOST/sms/sendbulkTrasferimento in blocco da un file (in più parti).
WhatsAppPOST/whatsapp/message/sendbulkTesto, media, modelli, interattivo (in più parti).
RCSPOST/rcs/message/sendbulkMessaggi RCS (in più parti).
TelegramPOST/telegram-sms/sendMessaggi Telegram.
EmailPOST/email/email-service/sendEmail con oggetto, corpo del messaggio e destinatari.
MessengerPOST/messenger/message/sendbulkMessaggi di Facebook Messenger (in più parti).
InstagramPOST/instagram/message/sendbulkMessaggi Instagram (in più parti).
PushPOST/push/message/sendNotifiche push (JSON).

Un esempio di invio tramite modello WhatsApp :

curl · /whatsapp/message/sendbulk
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

Imposta batchId su 0 per avviare un nuovo batch. Il campo destinationNo accetta più numeri separati da virgole. La risposta contiene l'ID del batch che utilizzi per leggere lo stato di ciascun destinatario.

SDK TypeScript

BroadNet pubblica un SDK ufficiale per TypeScript e Node.js : @broadnet/cpaas-sdk È disponibile su npm. Viene generato a partire dalla specifica BroadNet OpenAPI, include moduli CommonJS ed ES con definizioni di tipo complete e presenta una classe API per ogni funzionalità di canale. La sua unica dipendenza di runtime è axios, che npm installa insieme al pacchetto.

terminal
npm install @broadnet/cpaas-sdk axios
TypeScript · WhatsApp
import { 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

Per qualsiasi altro linguaggio, è necessario chiamare direttamente l'API REST (gli esempi Node.js, Python, Java, C#, Go e Ruby sopra riportati non utilizzano la libreria BroadNet) oppure generare un client a partire dalle specifiche OpenAPI.

Specifiche OpenAPI

L'API completa è descritta in un file OpenAPI 3.1: 329 percorsi e 376 operazioni su otto canali. Questa è una copia pubblica della specifica, priva di esempi interni. Importala in Postman o Insomnia, esplorala in Swagger UI o genera un client.

terminal
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

Preferisci Postman? Importa le specifiche per ottenere tutte le operazioni, oppure inizia con una piccola raccolta delle chiamate essenziali.

API HTTP legacy (/websmpp)

Gli account creati sulla piattaforma BroadNet dell'era SMPP possono utilizzare l'API HTTP legacy al percorso /websmpp. Questa API viene mantenuta attiva per le integrazioni esistenti ed è documentata nelle specifiche OpenAPI. Accetta le credenziali come parametri di richiesta (nome utente e password o chiave di accesso) anziché un token Bearer. Le nuove integrazioni devono utilizzare l'API REST descritta in precedenza.

Metodo HTTPPercorso del punto finaleDescrizione
GET/websmpp/websmsInvia un SMS. Aggiungi un orario e un offset GMT per programmarlo.user, pass (or accesskey), sid, mno, type, text, schtime, gmt
POST/websmpp/json/smsInviare con un oggetto campagna JSON che contenga le credenziali, il mittente, i numeri e il testo.campaign { username, password, sender, gsm, text, type }
GET/websmpp/websmsstatusStato di un messaggio inviato, tramite il suo ID di risposta.respid, format
POST/websmpp/api/dlrreportReport delle consegne per un intervallo di date, in formato foglio di calcolo.username, pass, from_date, to_date
GET/websmpp/hlr/lookupRicerca HLR per un singolo numero.username, password, destination
curl · legacy
# 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"

Domande frequenti

Come faccio ad autenticarmi?

Invia il tuo token di accesso nell'intestazione Authorization: Bearer di ogni richiesta. Il token proviene dal tuo account BroadNet ; non è prevista alcuna chiamata per la generazione del token API. Un token mancante o non valido viene rifiutato dal gateway API con HTTP 401 e un corpo JSON composto da due campi: error e message. Conserva il token in una variabile d'ambiente o in un gestore di segreti, mai nel controllo di versione o nel codice lato client.

Qual è l'URL di base?

Ogni esempio chiama la produzione, https://api.broadnet.me. Le credenziali di test, e l'indirizzo a cui inviare il traffico di prova, arrivano con il tuo accesso di test: richiedilo su /signup e rispondiamo entro un giorno lavorativo.

Come faccio a inviare testo in arabo o in altri formati Unicode?

Imposta messageType su UNICODE. Usa TEXT solo quando ogni carattere è presente nell'alfabeto GSM-7. In caso di dubbi, chiama POST /sms/identify con il messaggio: restituirà messageType, il conteggio dei caratteri, il numero di segmenti e i caratteri per segmento.

Cosa restituisce un invio andato a buon fine?

POST /sms/sendSms restituisce HTTP 200 e l'ID del messaggio come corpo della risposta. Gli invii massivi restituiscono un oggetto JSON con status, bulkSessionId, credits, deductcredits e bulkListInfo.

Come faccio a inviare un SMS a più destinatari?

Utilizzare POST /sms/sendbulk con un caricamento multipart: destinationNumberFile è un file CSV o TXT contenente numeri e bulkRequest è una stringa JSON con senderId, message, messageType e campaignName. I processi possono quindi essere elencati, messi in pausa, ripresi o interrotti tramite ID batch.

Come faccio a conoscere lo stato della consegna?

Lo stato di consegna viene inviato all'URL del webhook configurato sul tuo account. Per WhatsApp, lo stato di ciascun destinatario può essere letto anche da /whatsapp/message/bulk-insights.

Esiste un SDK ?

Sì, uno: l'SDK ufficiale TypeScript / Node.js, @broadnet/cpaas-sdk su npm, generato dalla specifica BroadNet OpenAPI. Per qualsiasi altro linguaggio, chiama direttamente l'API REST o genera un client dalla specifica OpenAPI 3.1 disponibile in /developers/openapi.yaml.

Che cos'è l'API /websmpp?

L'API HTTP legacy, mantenuta per le integrazioni esistenti dell'era SMPP. Accetta le credenziali come parametri di richiesta. Le nuove integrazioni devono utilizzare l'API REST Bearer-token documentata in questa pagina.

Inizia l'invio

Pronto a inviare il tuo primo SMS?