Webhook WhatsApp: instradare i messaggi direttamente al tuo server
Un webhook WhatsApp è un endpoint HTTPS che indichi tu, al quale Meta invia eventi: messaggi in arrivo, stati di consegna, cambiamenti della qualità e aggiornamenti dell'account. Su un numero Coexistence puoi impostare la destinazione sul tuo server, così le conversazioni non passano mai da un provider.
- Meta invia gli eventi direttamente al tuo URL
- Il tuo endpoint, non la piattaforma di un provider
- Un override per ogni account WhatsApp Business
Nessun addebito per 7 giorni. Annulla quando vuoi.
Cos'è l'intera integrazione: una destinazione HTTPS per account.
messages e smb_message_echoes, gli eventi del percorso dei messaggi instradati verso di te.
Il valore che Meta invia nell'handshake GET e che il tuo endpoint deve restituire.
Cosa invia davvero Meta a un webhook?
Eventi organizzati per categorie: distinguerli determina la tua architettura.
Il percorso dei messaggi trasporta ciò che inviano i clienti e, su un numero Coexistence, le copie di ciò che il tuo team invia dall'app WhatsApp Business. Questi sono i campi messages e smb_message_echoes, gli unici a contenere il testo delle conversazioni.
Il percorso operativo trasporta tutto il resto: account_update quando cambia lo stato di una connessione, phone_number_quality_update quando cambiano qualità o capacità di invio, account_alerts, account_review_update, business_capability_update e phone_number_name_update. Non contengono testo delle conversazioni e alimentano il monitoraggio.
Un provider che si inserisce nel percorso dei messaggi riceve il primo gruppo. Uno che non lo fa, no.
Come verifica Meta un endpoint?
Con una richiesta GET, prima di consegnare qualsiasi cosa. Il mancato superamento di questa verifica è il motivo più comune per cui una configurazione apparentemente completa non riceve mai un messaggio.
Meta chiama il tuo URL con hub.mode impostato su subscribe, il tuo hub.verify_token e un valore hub.challenge. Il tuo endpoint deve restituire quella challenge come corpo grezzo della risposta, senza JSON e senza aggiungere altro. In caso contrario, Meta non inizia mai la consegna e nessuna dashboard lo segnala.
L'endpoint deve inoltre usare HTTPS. Un endpoint che restituisce un 404 senza contenuto, o che si trova dietro un livello di autenticazione che rifiuta Meta, appare identico a una configurazione funzionante fino a quando il primo messaggio non arriva.
La destinazione può puntare al tuo server?
Sì, ed è questo l'aspetto che varia tra i provider.
Meta consente a un'app di sostituire la destinazione a cui un determinato account WhatsApp Business consegna i webhook. Impostiamo questo override sul tuo URL, spostando verso di te gli eventi del percorso dei messaggi inviati al nostro callback. Conserviamo gli eventi operativi, perché dashboard e avvisi sono costruiti su questi.
La conseguenza è architetturale, non una politica che pubblichiamo. Sul nostro lato non c'è un luogo in cui conservare il testo delle conversazioni, perché non ci viene mai consegnato. Un account senza override usa il nostro callback predefinito, dove il gestore scarta questi eventi senza salvarli.
Cosa succede alla destinazione quando un numero si riconnette?
Viene rimossa, ed è il problema a cui quasi nessuno pensa.
La destinazione non è una proprietà del numero di telefono. È un override sulla sottoscrizione della nostra app all'account WhatsApp Business. Quando una connessione viene rimossa, per la regola di inattività di quattordici giorni di Meta o per un altro motivo, l'app viene disinstallata da quell'account e l'override scompare con essa.
La riconnessione ripristina l'invio e il monitoraggio. Non ripristina la consegna al tuo server e nessun errore viene segnalato, quindi il primo indizio è un cliente che dice di non aver ricevuto risposta. Riapplichiamo l'override a ogni riconnessione, perché è successo a un numero reale che si era riconnesso correttamente ma poi era rimasto in silenzio.
Errori comuni
- Restituire JSON dalla richiesta GET di verifica. Meta vuole il valore grezzo di hub.challenge e nient'altro.
- Usare un URL temporaneo o di test. Meta continua a consegnare gli eventi anche dopo che lo strumento che lo ha generato smette di ascoltare.
- Presumere che la destinazione sopravviva a una riconnessione. Vive su una sottoscrizione dell'app e viene disinstallata insieme a essa.
- Mettere l'endpoint dietro un'autenticazione che rifiuta la richiesta di Meta.
EasyCoexistence imposta l'override del webhook sul tuo endpoint, lo verifica prima della chiamata e lo riapplica automaticamente dopo ogni riconnessione. Da US$ 9 per numero al mese, fino a US$ 2 con i volumi, con i primi 7 giorni gratuiti.
Domande frequenti
I miei messaggi passano da EasyCoexistence?
No. L'override invia gli eventi del percorso dei messaggi direttamente da Meta al tuo endpoint. Gli eventi di un account senza override usano il nostro callback e vengono scartati senza essere salvati.
Posso cambiare la destinazione in seguito?
Sì, in qualsiasi momento, dalla dashboard o tramite il connettore MCP. Passando null, la destinazione torna a quella predefinita.
Cosa succede se il mio server non è disponibile quando Meta consegna gli eventi?
Meta riprova per un certo periodo e poi interrompe i tentativi. I messaggi arrivano comunque nell'app WhatsApp Business sul telefono, quindi l'azienda non perde nulla anche quando l'integrazione non funziona.
Un webhook basta per più numeri?
Sì. Indica lo stesso endpoint per ogni numero e usa l'id del numero di telefono che riceve il payload per instradare gli eventi.
Continua a leggere
Pronto per iniziare?
Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.
Inizia la prova gratuitaNessun addebito per 7 giorni. Annulla quando vuoi.Verificato il