Integrare una API di messaggistica: REST, SMPP e webhook

Questa guida è rivolta a sviluppatori backend, solution architect e CTO che integrano un'applicazione con un provider di messaggistica per WhatsApp, SMS o email. Spiega quale interfaccia usare e come gestire autenticazione, idempotenza, rapporti di consegna, retry, limiti di frequenza e test, con forme di richieste e risposte a titolo illustrativo. Per sincronizzare le conversazioni in un CRM, vedi la guida complementare sul collegare un CRM con i webhook.

Quale interfaccia usare: REST, SMPP o webhook?

Usate REST per inviare, i webhook per ricevere e SMPP solo per SMS ad alto volume dove gestite già SMPP. Sono complementari più che concorrenti: la maggior parte delle integrazioni combina chiamate REST in uscita con webhook in ritorno.

Le sessioni SMPP (Short Message Peer-to-Peer) iniziano con un bind (transmitter, receiver o transceiver), inviano messaggi con submit_sm, ricevono ricevute di consegna e SMS in ingresso tramite deliver_sm e restano attive con enquire_link. È efficiente ma operativamente più pesante di HTTPS.

Come autenticarsi?

Usate il metodo più forte offerto dal provider, tenete i segreti fuori dal codice e autenticate entrambe le direzioni.

• Chiamate in uscita: chiavi API o bearer token OAuth 2.0 inviati nell'intestazione Authorization su TLS. Conservateli in un gestore di segreti e ruotateli con regolarità e dopo cambi di personale.
• SMPP: system ID e password al momento del bind, di solito limitati a indirizzi IP consentiti e, dove supportato, su TLS.
• Webhook in ingresso: verificate la firma di ogni evento. Meta firma i payload dei webhook della WhatsApp Cloud API con una firma HMAC-SHA256 nell'intestazione X-Hub-Signature-256, calcolata con il segreto della vostra app; i provider di solito offrono uno schema simile. Calcolate la firma sul corpo grezzo prima del parsing.

Usate credenziali separate per ambiente, così una chiave di prova compromessa non può inviare traffico di produzione.

Come inviare un messaggio in sicurezza?

Inviate tramite una coda, includete una chiave di idempotenza e trattate la risposta come "accettato", non "consegnato".

Richiesta di invio a titolo illustrativo

La forma seguente è pseudo-JSON a scopo illustrativo, non l'API di uno specifico provider.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Risposta a titolo illustrativo

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Memorizzate subito message_id rispetto al vostro riferimento. Tutto ciò che accade dopo arriva in modo asincrono.

Perché l'idempotenza è importante?

Perché le reti vanno in timeout dopo che il server ha già agito. Se la richiesta di invio va in timeout e riprovate alla cieca, il cliente può ricevere due OTP o due avvisi di spedizione. Una chiave di idempotenza permette al server di riconoscere il retry e restituire il risultato originale.

Regole che funzionano:

1. Derivate la chiave dall'evento di business (ad esempio ID ordine più tipo di evento), non da un valore casuale per tentativo.
2. Riutilizzate la stessa chiave per ogni retry dello stesso invio.
3. Conservate le chiavi abbastanza a lungo da coprire la vostra finestra di retry.
4. Se il provider non supporta le chiavi, deduplicate dal vostro lato prima di inviare.

La bozza IETF dell'intestazione Idempotency-Key standardizza questo schema per le API HTTP; le implementazioni dei provider variano, quindi leggete la loro documentazione.

Come funzionano i rapporti di consegna?

Lo stato di consegna arriva dopo come eventi: da webhook per WhatsApp e la maggior parte delle API REST, e da ricevute deliver_sm su SMPP. Il significato degli stati cambia per canale; la nostra guida agli stati di consegna dei messaggi spiega ciascuno.

Webhook di stato a titolo illustrativo

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Gestite gli eventi di stato in modo difensivo:

• Deduplicate su event_id, oppure su ID del messaggio più stato.
• Non retrocedete mai un messaggio da letto a consegnato quando gli eventi arrivano fuori ordine.
• Rispondete subito con 2xx, poi elaborate da una coda.
• Registrate i codici di errore per i messaggi falliti e decidete quali sono riprovabili.
• Aspettatevi lacune: alcune rotte SMS restituiscono ricevute limitate e lo stato di lettura dipende dal canale e dalle impostazioni dell'utente.

Come gestire retry e limiti di frequenza?

Riprovate solo ciò che può riuscire, rallentate in modo esponenziale con jitter e rispettate i segnali del server.

L'RFC 9110 definisce l'intestazione Retry-After, che può riportare secondi o una data. Mettete un limitatore di frequenza lato client davanti ai vostri invii, così restate sotto i limiti documentati dal provider anziché scoprirli tramite errori. WhatsApp prevede anche limiti lato Meta su quanti clienti unici potete contattare, descritti in limiti di messaggistica e valutazione di qualità.

Come testare prima della messa online?

Testate i percorsi di errore, non solo il percorso felice.

Checklist pre-produzione

1. Inviate ogni template con valori di lunghezza reale, compreso testo in arabo.
2. Forzate un timeout e confermate che il retry non duplichi.
3. Inviate a un numero non valido e confermate che l'errore sia gestito senza retry.
4. Riproducete un webhook due volte e fuori ordine; confermate un unico stato finale.
5. Inviate un webhook con una firma errata; confermate che venga rifiutato.
6. Provocate dei 429 con un test di carico sulla sandbox, se consentito.
7. Ruotate una chiave API e confermate l'assenza di interruzioni.
8. Verificate che i log contengano ID dei messaggi ma non i corpi completi dei messaggi né i codici OTP.
9. Eseguite un piccolo pilota in produzione con numeri interni su ogni canale.

Le sandbox raramente riproducono con esattezza il comportamento di operatori e Meta, quindi mantenete il monitoraggio nelle prime settimane di produzione.

Esempio pratico: un servizio di OTP e notifiche d'ordine

"Qafilah Logistics" (fittizia), azienda di spedizioni in Arabia Saudita, invia aggiornamenti d'ordine su WhatsApp con riserva SMS e OTP di autenticazione.

• Architettura: gli eventi d'ordine vanno in una coda; un worker di invio chiama l'API REST con una chiave di idempotenza shipment-id:event.
• Fallback: se WhatsApp restituisce uno stato di fallito per un utente non WhatsApp, il worker invia un SMS con una nuova chiave, shipment-id:event:sms.
• OTP: i codici scadono in fretta, quindi gli invii OTP non vengono riprovati dopo la finestra di scadenza; l'utente richiede un nuovo codice. Vedi la guida ai messaggi di autenticazione OTP.
• Ricevute: un ricevitore di webhook verifica le firme, deduplica gli eventi e aggiorna una tabella di stato che non retrocede mai.
• Limiti: un limitatore a token bucket mantiene la frequenza di invio per canale sotto i limiti documentati.

Quali sono gli errori di integrazione più comuni?

• Considerare "accettato" come "consegnato".
• Riprovare con una nuova chiave di idempotenza a ogni tentativo.
• Eseguire elaborazioni pesanti dentro la richiesta del webhook.
• Saltare la verifica della firma sui webhook.
• Riprovare in ciclo gli errori di validazione 4xx.
• Registrare nei log i codici OTP e il contenuto completo dei messaggi.
• Usare credenziali di produzione negli ambienti di prova.

Come vi aiuta OmniChannels.ai

OmniChannels.ai, sviluppata da BroadNet Technologies, offre una API REST/JSON documentata pubblicamente con specifica OpenAPI 3.1 e un SDK TypeScript, che copre SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, email e push, compresi i template di autenticazione WhatsApp con OTP one-tap, zero-tap e copy-code. I webhook riportano gli stati di consegna in un unico formato normalizzato, SMPP 3.4 su TLS serve gli SMS ad alto volume e un server MCP collega gli agenti IA. I rapporti di consegna (DLR) con filtri ed esportazione CSV aiutano a riconciliare ciò che la vostra integrazione ha inviato. Iniziate dalla documentazione per sviluppatori e dalla guida rapida.