webhook user_preferences di WhatsApp: quando un cliente interrompe o riprende i messaggi di marketing
Il webhook user_preferences segnala a un'azienda che un utente WhatsApp ha interrotto o ripreso i propri messaggi di marketing tramite l'impostazione Offers and announcements. Ogni evento contiene la categoria marketing_messages, un valore stop o resume, una frase di dettaglio, il wa_id e il BSUID dell'utente e un timestamp Unix. I feedback Interessato e Non interessato nella stessa impostazione non lo attivano.
easyCoexistence collega il numero della tua app WhatsApp Business all'API Cloud di Meta tramite Coexistence, così la tua AI e le automazioni funzionano sul numero che mantieni nell'app.
Valori che una preferenza può assumere: stop e resume, entrambi nella categoria marketing_messages.
Il codice di errore dello stato failed per un template di marketing inviato a un utente che ha interrotto i messaggi di marketing.
Destinazione di invio di user_preferences: non è un campo che un WhatsApp Business Account o un numero può sovrascrivere.
Il permesso che un'app deve avere per i webhook diversi da messages e calls, user_preferences incluso.
Cosa attiva il webhook user_preferences?
Un cliente che apre Offers and announcements in WhatsApp e sceglie di interrompere o, più tardi, riprendere i messaggi di marketing della tua azienda. Solo queste due azioni lo attivano. La stessa impostazione permette al cliente di segnare Interessato o Non interessato, e questo feedback non invia alcun webhook, anche se Non interessato può abbassare il limite di marketing per utente tra te e quel cliente e apre una seconda schermata che propone di interrompere del tutto i messaggi di marketing. Solo se poi tocca stop, user_preferences si attiva.
Cosa contiene il payload?
Un array user_preferences accanto a un array contacts, sotto il nome di campo user_preferences. Qui il timestamp è un intero, mentre i webhook di stato lo inviano come stringa. wa_id viene omesso quando il cliente usa un username e il suo numero di telefono non può essere condiviso, user_id quando gli ID utente con ambito aziendale non sono attivi per la tua azienda, e parent_user_id a meno che i BSUID padre non siano attivi. Ecco l'esempio di ripresa di Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}Cosa deve fare il tuo sistema con uno stop?
Registralo sul cliente e tienilo fuori da ogni invio di marketing finché non arriva una ripresa. Il campo detail riporta o "User requested to stop marketing messages" o "User requested to resume marketing messages", ma il codice deve leggere value.
- Salva la preferenza sia per BSUID sia per numero di telefono, perché in un dato evento può mancare uno dei due.
- Escludi il cliente dagli invii di template di marketing; Meta li rifiuterebbe comunque con 131050.
- Applica la preferenza solo per cliente: Meta non applica mai una preferenza a livello di BSUID padre.
- Alla ripresa, rimuovi l'esclusione e conserva il tuo registro di opt-in, come richiede la politica di opt-in di Meta.
Cosa succede se user_preferences non arriva mai al tuo server?
Meta applica comunque lo stop, quindi un webhook mancante ti costa un invio fallito, non una violazione di policy. Quando invii un template di marketing a chi ha interrotto, l'API accetta la richiesta, non invia il messaggio e attiva un webhook di stato con stato failed, codice 131050 e il titolo "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". Tratta questo fallimento esattamente come un evento di stop: registralo e sopprimi ulteriori invii di marketing a quel cliente.
Come funziona su un numero collegato tramite easyCoexistence?
user_preferences non è uno dei campi per cui Meta consente un override della destinazione, quindi lo consegna solo al callback predefinito dell'app che ha sottoscritto l'account. Per un numero collegato tramite easyCoexistence, quell'app è quella di easyCoexistence, che oggi non sottoscrive user_preferences: l'evento quindi non arriva né a una destinazione diretta né a un Forward URL. Lo stato failed con 131050 invece arriva, perché viaggia sul campo messages.
Se la tua AI invia template di marketing con send_template, conserva la lista di stop nel tuo sistema e controllala prima: easyCoexistence non ne tiene una.
Errori comuni
- Trattare Non interessato come uno stop. Non invia alcun webhook e non blocca la consegna, anche se può abbassare il limite di marketing per utente per quel cliente.
- Usare come chiave solo wa_id. Manca per i clienti con un username il cui numero non può essere condiviso; salva anche il BSUID.
- Applicare uno stop a tutti sotto un BSUID padre. Meta applica le preferenze per utente, mai a livello padre.
- Riprovare dopo 131050 invece di registrarlo come stop. Ogni tentativo fallisce allo stesso modo.
I template di marketing inviati tramite essa partono dal tuo WhatsApp Business Account, e gli stati failed che segnalano un cliente che ha interrotto arrivano al tuo server direttamente o come forward firmati. Da US$ 9 a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con 3 giorni di prova gratuita.
Domande frequenti
Uno stop blocca anche le risposte ai messaggi del cliente?
La documentazione di Meta descrive lo stop come riferito ai messaggi di marketing, e l'errore restituito cita i messaggi di marketing. Le risposte a un cliente che ti ha scritto sono messaggi di servizio, una categoria diversa.
Bloccare la tua azienda attiva user_preferences?
No. Il webhook si attiva solo con stop e resume nell'impostazione Offers and announcements. Il blocco è un'azione separata e non viene segnalato su questo campo.
Una ripresa conta come opt-in?
Significa che il cliente ha scelto di ricevere di nuovo i tuoi messaggi di marketing. I tuoi obblighi di opt-in secondo la policy di Meta restano validi, quindi conserva la registrazione di come e quando quel cliente ha accettato di essere contattato da te.
A quale campo webhook devo sottoscrivermi?
user_preferences, in App Dashboard sotto WhatsApp > Configuration, sull'app sottoscritta al WhatsApp Business Account. È un campo separato da messages e richiede whatsapp_business_management.
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 gratuitaVerificato il