Webhook user_preferences de WhatsApp : quand un client arrête ou reprend vos messages marketing
Le webhook user_preferences indique à une entreprise qu'un utilisateur WhatsApp a arrêté ou repris ses messages marketing via le paramètre Offres et annonces. Chaque événement contient la catégorie marketing_messages, une valeur stop ou resume, une phrase de détail, le wa_id et le BSUID de l'utilisateur, ainsi qu'un horodatage Unix. Les retours Intéressé et Pas intéressé dans ce même paramètre ne déclenchent pas ce webhook.
easyCoexistence relie le numéro de votre application WhatsApp Business à la Cloud API de Meta grâce à Coexistence, afin que votre IA et vos automatisations fonctionnent sur le numéro que vous gardez dans l'application.
Valeurs qu'une préférence peut prendre : stop et resume, toutes deux dans la catégorie marketing_messages.
Le code d'erreur du statut failed pour un template marketing envoyé à un utilisateur qui a arrêté vos messages marketing.
Là où Meta envoie user_preferences : c'est un champ qu'aucun WhatsApp Business Account ni aucun numéro ne peut remplacer.
La permission dont une application a besoin pour les webhooks autres que messages et calls, user_preferences inclus.
Qu'est-ce qui déclenche le webhook user_preferences ?
Un client qui ouvre Offres et annonces dans WhatsApp et choisit d'arrêter, ou plus tard de reprendre, vos messages marketing. Ces deux actions sont les seuls déclencheurs. Le même paramètre permet aussi au client d'indiquer Intéressé ou Pas intéressé, un retour qui n'envoie aucun webhook. Pas intéressé peut toutefois abaisser la limite de messages marketing par utilisateur entre vous et ce client, et ouvre un second écran proposant d'arrêter tous les messages marketing. Ce n'est que s'il appuie ensuite sur arrêter que user_preferences se déclenche.
Que contient le payload ?
Un tableau user_preferences à côté d'un tableau contacts, sous le nom de champ user_preferences. Ici l'horodatage est un entier, alors que les webhooks de statut l'envoient sous forme de chaîne. wa_id est omis lorsque le client utilise un nom d'utilisateur et que son numéro de téléphone ne peut pas être partagé, user_id lorsque les identifiants utilisateur propres à l'entreprise ne sont pas activés pour votre entreprise, et parent_user_id sauf si les BSUID parents sont activés. Voici l'exemple de reprise donné par 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"
}
]
}
]
}Que doit faire votre système avec un arrêt ?
Enregistrez-le pour ce client et excluez-le de tout envoi marketing jusqu'à l'arrivée d'une reprise. Le champ detail indique soit « User requested to stop marketing messages », soit « User requested to resume marketing messages », mais c'est value que votre code doit lire.
- Stockez la préférence par BSUID et par numéro de téléphone, car l'un ou l'autre peut manquer selon l'événement.
- Excluez le client des envois de templates marketing ; Meta les refuserait de toute façon avec 131050.
- Appliquez-la au seul client concerné : Meta n'applique jamais de préférence au niveau du BSUID parent.
- À la reprise, levez l'exclusion, et conservez votre propre preuve d'opt-in, comme l'exige la politique d'opt-in de Meta.
Que se passe-t-il si user_preferences n'arrive jamais sur votre serveur ?
Meta applique quand même l'arrêt, donc un webhook manquant vous coûte un envoi en échec, pas une violation de politique. Lorsque vous envoyez un template marketing à quelqu'un qui a arrêté, l'API accepte la requête, n'envoie pas le message et déclenche un webhook de statut avec status failed, le code 131050 et le titre « Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business ». Traitez cet échec exactement comme un événement d'arrêt : enregistrez-le et suspendez les envois marketing suivants à ce client.
Comment cela fonctionne-t-il sur un numéro connecté via easyCoexistence ?
user_preferences ne fait pas partie des champs pour lesquels Meta autorise une destination de remplacement ; Meta ne le livre donc que sur le callback par défaut de l'application abonnée au compte. Pour un numéro connecté via easyCoexistence, cette application est celle d'easyCoexistence, qui ne s'abonne pas aujourd'hui à user_preferences : l'événement n'atteint donc ni une destination directe ni une Forward URL. Le statut failed 131050, lui, y parvient, car il transite par le champ messages.
Si votre IA envoie des templates marketing avec send_template, tenez à jour votre propre liste d'arrêts et vérifiez-la avant tout envoi : easyCoexistence n'en tient pas une.
Erreurs courantes
- Confondre Pas intéressé avec un arrêt. Il n'envoie aucun webhook et n'interrompt pas la diffusion, même s'il peut abaisser la limite de messages marketing de ce client.
- Indexer les préférences sur le seul wa_id. Il est omis pour les clients qui utilisent un nom d'utilisateur et dont le numéro ne peut pas être partagé ; stockez aussi le BSUID.
- Appliquer un arrêt à tous les utilisateurs d'un BSUID parent. Meta applique les préférences utilisateur par utilisateur, jamais au niveau parent.
- Réessayer après un 131050 au lieu de l'enregistrer comme un arrêt. Chaque tentative échoue de la même manière.
Les templates marketing envoyés par ce biais partent de votre propre WhatsApp Business Account, et les statuts en échec qui signalent un client ayant arrêté arrivent à votre serveur directement ou sous forme de transferts signés. De US$ 9 à US$ 0,75 par numéro et par mois, dégressif à mesure que vous ajoutez des numéros, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Un arrêt bloque-t-il aussi les réponses aux messages du client ?
La documentation de Meta décrit l'arrêt comme couvrant les messages marketing, et l'erreur renvoyée mentionne explicitement les messages marketing. Les réponses à un client qui vous a écrit sont des messages de service, une autre catégorie.
Bloquer l'entreprise déclenche-t-il user_preferences ?
Non. Le webhook ne se déclenche que sur l'arrêt et la reprise dans le paramètre Offres et annonces. Le blocage est une action distincte et n'est pas signalé dans ce champ.
Une reprise compte-t-elle comme un opt-in ?
Elle signifie que le client a choisi de recevoir de nouveau vos messages marketing. Vos obligations d'opt-in au titre de la politique de Meta restent valables : conservez donc la trace de la date et de la manière dont ce client a accepté d'être contacté.
À quel champ de webhook dois-je m'abonner ?
user_preferences, dans l'App Dashboard sous WhatsApp > Configuration, sur l'application abonnée au WhatsApp Business Account. C'est un champ distinct de messages, et il nécessite whatsapp_business_management.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le