--- title: "Integrare una API di messaggistica: REST, SMPP e webhook" description: "Guida per sviluppatori all'integrazione di una API di messaggistica: REST, SMPP e webhook, autenticazione, idempotenza, rapporti di consegna, retry e test." canonical: "https://omnichannels.ai/it/blog/messaging-api-integration-guide/" language: "it" updated: "2026-10-10" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "messaging api integration guide" keywords: ["api sms o smpp", "webhook api whatsapp stato di consegna", "chiave di idempotenza api messaggistica", "rapporti di consegna dlr", "limite di frequenza api 429 retry", "test sandbox api messaggistica"] published: "2026-10-09" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 9 answer: "Usate una API REST per inviare messaggi dalle applicazioni, SMPP solo per SMS ad alto volume dove gestite già un'infrastruttura di livello telecom, e i webhook per ricevere rapporti di consegna e messaggi in ingresso. Autenticate ogni chiamata, inviate una chiave di idempotenza con ogni invio così i retry non duplicano mai i messaggi, trattate lo stato di consegna come asincrono, rallentate sugli errori HTTP 429 e 5xx e testate i percorsi di errore in una sandbox prima della produzione." takeaways: ["REST si adatta alla maggior parte delle integrazioni applicative; SMPP è un protocollo binario persistente pensato per il throughput degli SMS tra sistemi di messaggistica.", "Una richiesta di invio accettata significa che il messaggio è stato messo in coda, non consegnato; lo stato finale arriva dopo tramite webhook o ricevute di consegna SMPP.", "HTTP 429 Too Many Requests è definito nell'RFC 6585; i client dovrebbero rallentare e rispettare l'eventuale intestazione Retry-After.", "Le chiavi di idempotenza permettono di riprovare in sicurezza un invio andato in timeout senza inviare al cliente due volte lo stesso messaggio.", "Meta firma i webhook della WhatsApp Cloud API, così chi li riceve può verificare che gli eventi provengano davvero da Meta."] faq: - q: "Conviene integrare un provider di messaggistica tramite REST o SMPP?" a: "Scegliete REST per quasi tutti i casi d'uso applicativi: funziona su HTTPS, è semplice da proteggere e supporta canali ricchi come WhatsApp. Scegliete SMPP quando inviate grandi volumi di SMS, gestite già client SMPP e avete bisogno di una connessione persistente con windowing. SMPP vale solo per gli SMS; WhatsApp, email e canali social usano API HTTP." - q: "Che cos'è una chiave di idempotenza in una API di messaggistica?" a: "Una chiave di idempotenza è un valore univoco che il vostro sistema invia con una richiesta, così il server può riconoscere le ripetizioni. Se la chiamata di invio va in timeout e riprovate con la stessa chiave, il provider restituisce il risultato originale anziché inviare un secondo messaggio. L'IETF ha una bozza di standard per un'intestazione HTTP Idempotency-Key, ma i provider implementano le chiavi in modi diversi, quindi consultate la documentazione." - q: "Perché a volte i rapporti di consegna arrivano fuori ordine?" a: "Gli eventi di stato sono generati da sistemi diversi, come operatori, Meta e il provider, e consegnati su reti con retry. Un evento di lettura può arrivare prima di un evento di consegna e i duplicati sono normali. Conservate ogni stato con il suo timestamp, non riportate mai un messaggio da uno stato successivo a uno precedente e deduplicate per ID del messaggio e stato." - q: "Come deve gestire i limiti di frequenza la mia applicazione?" a: "Leggete i limiti documentati dal provider, mettete in coda gli invii in uscita anziché lanciarli direttamente dalle richieste degli utenti e usate un limitatore a token bucket o simile dal vostro lato. Quando ricevete HTTP 429, fermatevi e riprovate dopo il tempo indicato nell'intestazione Retry-After oppure con backoff esponenziale e jitter. Non riprovate gli errori di validazione 4xx." - q: "Cosa testare in una sandbox di messaggistica?" a: "Testate errori di autenticazione, numeri di telefono non validi, errori nelle variabili dei template, timeout con retry idempotenti, webhook duplicati e fuori ordine, risposte ai limiti di frequenza, messaggi lunghi e in arabo e la verifica della firma dei webhook. Poi eseguite un piccolo pilota in produzione con numeri reali, perché le sandbox raramente riproducono con esattezza il comportamento di operatori o Meta." sources: - title: "Cloud API webhooks — Meta for Developers" url: "https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks" - title: "RFC 6585: Additional HTTP Status Codes (429 Too Many Requests)" url: "https://www.rfc-editor.org/rfc/rfc6585" - title: "RFC 9110: HTTP Semantics" url: "https://www.rfc-editor.org/rfc/rfc9110" - title: "The Idempotency-Key HTTP Header Field — IETF draft" url: "https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/" - title: "SMPP protocol specification resources — SMPP.org" url: "https://smpp.org/" --- # Integrare una API di messaggistica: REST, SMPP e webhook Canonical: https://omnichannels.ai/it/blog/messaging-api-integration-guide/ Language: it Publisher: OmniChannels.ai by BroadNet Technologies 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](/it/blog/connect-crm-omnichannel-inbox-webhooks/). ## 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. | Aspetto | API REST | SMPP | Webhook | |---|---|---|---| | Direzione | La vostra app → provider | Bidirezionale su un'unica sessione | Provider → la vostra app | | Trasporto | Richiesta/risposta HTTPS | Sessione TCP persistente, PDU binarie | HTTPS POST al vostro endpoint | | Canali | WhatsApp, SMS, email, altri | Solo SMS | Eventi di tutti i canali | | Uso tipico | Inviare messaggi, gestire template, interrogare lo stato | SMS massivi tra sistemi di messaggistica | Stato di consegna, messaggi in ingresso | | Punti di forza | Semplice, compatibile con i firewall, payload ricchi | Throughput, windowing, standard telecom | Tempo reale, nessun polling | | Da tenere presente | Limiti di frequenza, timeout | Gestione delle sessioni, bind, keep-alive | Retry, duplicati, sicurezza | 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. ```json POST /v1/messages Authorization: Bearer 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 ```json 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](/it/blog/message-delivery-status-explained/) spiega ciascuno. ### Webhook di stato a titolo illustrativo ```json POST /webhooks/messaging X-Signature: sha256= { "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. | Risposta | Significato | Azione | |---|---|---| | 2xx | Accettato | Memorizzare l'ID, attendere lo stato | | 400 / 422 | Richiesta non valida (numero, template, variabili) | Non riprovare; correggere i dati | | 401 / 403 | Problema di autenticazione o permessi | Non riprovare; avvisare | | 409 | Conflitto, spesso una chiave di idempotenza duplicata | Recuperare il risultato originale | | 429 | Troppe richieste (RFC 6585) | Attendere Retry-After o rallentare | | 5xx / timeout | Errore del server o di rete | Riprovare con la stessa chiave di idempotenza e backoff | 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à](/it/blog/whatsapp-messaging-limits-quality-rating/). ## 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](/it/blog/otp-authentication-messages-guide/). - **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](/developers/webhooks/) riportano gli stati di consegna in un unico formato normalizzato, [SMPP 3.4](/developers/smpp/) su TLS serve gli SMS ad alto volume e un [server MCP](/developers/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](/developers/) e dalla [guida rapida](/developers/quickstart/).