Trasferisci il tuo traffico SMS a BroadNet da qualsiasi provider.

Mappa la tua API attuale su BroadNet

La maggior parte API SMS condivide alcuni concetti simili, seppur con nomi diversi. Individua il concetto nella prima colonna, indipendentemente dal nome utilizzato dal tuo provider, e usa l'equivalente BroadNet. I nomi dei campi sono esattamente come appaiono nelle specifiche OpenAPI.

Ecco lo stesso invio come singola richiesta. Sostituisci i campi mittente, destinatario e testo del tuo provider con senderId, destinationNumber e message :

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "destinationNumber": "447700900101",
    "message": "Your code is 8123",
    "messageType": "TEXT"
  }'

# 200 OK — the response body is the message ID, e.g. 2603121407537573731

Per verificare un messaggio, interroga il suo stato utilizzando l'ID del messaggio restituito dalla richiesta di invio:

# Status lookup on the legacy HTTP API (/websmpp), by message ID
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=2603121407537573731&format=json" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

# "status": "DELIVRD"   (or UNDELIV, EXPIRED, REJECTD)

Sposta i tuoi ID mittente

Gli ID mittente alfanumerici e i codici brevi sono generalmente portabili, fatte salve le norme di registrazione di ciascun operatore e autorità di regolamentazione. La registrazione è legata al percorso del traffico, quindi è importante pianificarla prima che qualsiasi messaggio di produzione venga inviato a BroadNet.

1. 1

   Elenca ogni ID mittente, i paesi di destinazione e il tipo di traffico che trasporta: OTP, transazionale o di marketing.

2. 2

   Verifica le normative di ciascun paese. Negli Emirati Arabi Uniti, gli ID del mittente vengono registrati secondo le norme TDRA tramite l'operatore, un ID per entità giuridica per caso d'uso. In Arabia Saudita, invece, è necessaria l'approvazione CST e dell'operatore, e i mittenti stranieri si vincolano tramite un aggregatore locale autorizzato CST.

3. 3

   Il tuo tecnico addetto alla migrazione invia le registrazioni per le rotte di BroadNet e il team di conformità di BroadNet segue ciascuna di esse fino all'approvazione.

4. 4

   Avvia l'invio parallelo in un Paese solo dopo che l'ID mittente è stato approvato per le rotte di BroadNet in quel Paese. Fino ad allora, continua a inviare tramite il tuo provider attuale.

Le regole per ciascun mercato sono riportate nelle pagine dedicate ai regolamenti. Normative sugli SMS per paese

Eseguire entrambi i provider in parallelo

Mantieni attivo il tuo provider attuale e aggiungi BroadNet come seconda rotta dietro uno switch nel tuo codice. Invia prima chiamate ai tuoi numeri verificati, poi a una piccola quantità di traffico reale e confronta le due rotte sulle stesse destinazioni.

Confronta, per paese e operatore:

• La combinazione degli stati di consegna: consegnato, non consegnato, scaduto e rifiutato.
• Il tempo che intercorre tra l'invio di un messaggio e la ricezione della conferma di consegna.
• Il mittente visualizzato sul telefono.
• Il conteggio dei segmenti per lo stesso testo, da POST /sms/identify.

Scegli il percorso per destinatario anziché per messaggio, in modo che tutti i tentativi di invio OTP per un utente passino attraverso lo stesso provider. Un'interfaccia di routing minimale:

// Send a share of recipients through BroadNet; the rest stay on your
// current provider. BROADNET_SHARE is a percentage (0-100) you control.
const BROADNET_SHARE = Number(process.env.BROADNET_SHARE ?? "0");

// Same recipient -> same bucket, so OTP retries stay on one provider.
function bucket(to: string): number {
  let h = 0;
  for (const c of to) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

export async function sendSms(to: string, text: string, senderId: string) {
  if (bucket(to) < BROADNET_SHARE) return sendViaBroadNet(to, text, senderId);
  return sendViaCurrentProvider(to, text, senderId); // your existing code
}

async function sendViaBroadNet(to: string, text: string, senderId: string) {
  const res = await fetch("https://api.broadnet.me/sms/sendSms", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
      "Content-Type": "application/json",
    },
    // Use UNICODE for non-GSM text; POST /sms/identify tells you which.
    body: JSON.stringify({ senderId, destinationNumber: to, message: text, messageType: "TEXT" }),
  });
  if (!res.ok) throw new Error(`BroadNet send failed: ${res.status}`);
  return { provider: "broadnet", messageId: await res.text() };
}

Aumentare il traffico gradualmente

Trasferisci il volume di produzione su BroadNet gradualmente, un paese o un caso d'uso alla volta. Rimani in ogni fase finché le ricevute di consegna non corrispondono a quelle inviate, quindi passa alla successiva.

1. Test

   Utilizza solo i tuoi numeri verificati. Conferma l'ID del mittente, il testo del messaggio e la conferma di consegna.

2. 5%

   Una piccola percentuale di traffico reale. Il traffico OTP verso un singolo paese restituisce conferme di consegna rapide e chiare.

3. 25%

   Un volume sufficiente per confrontare le tariffe di consegna e i tempi di ricezione con il tuo attuale fornitore.

4. 100%

   Tutto il traffico per quel paese o caso d'uso. Il tuo provider attuale rimane attivo finché le ricevute di consegna non corrispondono a quanto hai inviato.

Quanto tempo ci vuole

L'incremento del traffico richiede il tempo che si desidera. Il processo di onboarding segue un percorso predefinito: rispondiamo a una richiesta di accesso di prova entro un giorno lavorativo, l'integrazione tecnica richiede dai 2 ai 5 giorni lavorativi e la convalida del percorso con l'approvazione dell'ID mittente richiede dai 3 ai 10 giorni lavorativi. Nella maggior parte dei mercati, il passaggio dalla fase di individuazione a quella di lancio avviene in 5-15 giorni lavorativi; nei mercati in cui le autorità di regolamentazione impiegano più tempo per approvare gli ID mittente, i tempi sono più lunghi. Consulta i passaggi per l'onboarding

Ritorna al tuo provider attuale senza interruzioni del servizio

Per annullare l'impostazione, utilizzare lo stesso interruttore in senso inverso: ridurre la percentuale di traffico inviato tramite BroadNet all'ultimo passaggio che ha funzionato, oppure a zero. L'integrazione corrente e le relative registrazioni dell'ID mittente rimangono attive, quindi è sufficiente ridurre la percentuale. Non è necessario ricostruire nulla.

• Mantieni attive le credenziali del tuo attuale provider, le registrazioni dell'ID mittente e l'endpoint webhook finché tutto il traffico non sarà stato trasferito e le ricevute di consegna non corrisponderanno a quanto hai inviato.
• Prima di iniziare, concordate quali fattori scatenano un rollback, ad esempio un calo della percentuale di messaggi recapitati in un determinato Paese, e chi è autorizzato a deciderlo.
• Mantieni attivo il gestore webhook anche dopo un rollback: le conferme di consegna per i messaggi già inviati tramite BroadNet potrebbero comunque arrivare.
• Disattiva il vecchio percorso solo dopo che tutto il traffico è transitato senza intoppi attraverso BroadNet e le ricevute di consegna corrispondono a quanto inviato.

Chi è responsabile di cosa?

Una migrazione coinvolge il tuo codice, le registrazioni dei mittenti e il traffico in tempo reale. Ecco come viene suddiviso il lavoro.

Documentazione correlata

Domande frequenti