InloggenGratis proefperiode starten
Meta Tech Provider

WhatsApp user_preferences-webhook: wanneer een klant marketingberichten stopzet of hervat

De user_preferences-webhook meldt een bedrijf dat een WhatsApp-gebruiker zijn marketingberichten heeft gestopt of hervat via de instelling Aanbiedingen en aankondigingen. Elke gebeurtenis bevat de categorie marketing_messages, een waarde stop of resume, een detailzin, de wa_id en BSUID van de gebruiker en een Unix-tijdstempel. Geïnteresseerd en Niet geïnteresseerd in dezelfde instelling activeren hem niet.

easyCoexistence verbindt het nummer van je WhatsApp Business-app met de Cloud API van Meta via Coexistence, zodat je AI en automatiseringen werken op het nummer dat je in de app houdt.

2

Waarden die een voorkeur kan aannemen: stop en resume, beide in de categorie marketing_messages.

131050

De failed-statuscode voor een marketing-template verstuurd naar een gebruiker die je marketingberichten heeft gestopt.

Default callback

Waar Meta user_preferences verstuurt: het is geen veld dat een WhatsApp Business Account of nummer kan overschrijven.

whatsapp_business_management

De permissie die een app nodig heeft voor webhooks buiten messages en calls, inclusief user_preferences.

Wat activeert de user_preferences-webhook?

Een klant die Aanbiedingen en aankondigingen opent in WhatsApp en kiest om marketingberichten van je bedrijf te stoppen, of later weer te hervatten. Alleen die twee acties zijn triggers. Dezelfde instelling laat een klant ook Geïnteresseerd of Niet geïnteresseerd aantikken, en die feedback verstuurt geen webhook. Niet geïnteresseerd kan wel het marketinglimiet per gebruiker tussen jou en die klant verlagen, en opent een tweede scherm met het aanbod alle marketingberichten te stoppen. Pas als die klant dan op stoppen tikt, wordt user_preferences geactiveerd.

Wat bevat de payload?

Een array user_preferences naast een array contacts, onder de veldnaam user_preferences. De tijdstempel is hier een integer, terwijl statuswebhooks die als string versturen. wa_id ontbreekt wanneer de klant een gebruikersnaam gebruikt en zijn telefoonnummer niet gedeeld kan worden, user_id wanneer user-ID's met bedrijfsbereik niet voor je bedrijf zijn ingeschakeld, en parent_user_id tenzij parent-BSUID's aanstaan. Het voorbeeld van Meta voor een hervatting:

Meta's example: a customer resumes marketing messages
{
  "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"
        }
      ]
    }
  ]
}

Wat moet je systeem doen met een stop?

Sla de stop op bij de klant en houd die uit elke marketingverzending tot er een hervatting binnenkomt. Het detailveld leest ofwel "User requested to stop marketing messages" of "User requested to resume marketing messages", maar je code leest value.

  • Sla de voorkeur op per BSUID en per telefoonnummer, omdat bij een gebeurtenis een van beide kan ontbreken.
  • Sluit de klant uit van marketing-templateverzendingen; Meta zou ze toch al weigeren met 131050.
  • Pas het alleen per klant toe: Meta past een voorkeur nooit toe op parent-BSUID-niveau.
  • Bij een hervatting hef je de uitsluiting op, en bewaar je je eigen opt-in-registratie zoals het opt-in-beleid van Meta vereist.

Wat als user_preferences nooit je server bereikt?

Meta handhaaft de stop toch, dus een ontbrekende webhook kost je een mislukte verzending, geen beleidsschending. Wanneer je een marketing-template stuurt naar iemand die gestopt is, accepteert de API het verzoek, verstuurt hij het bericht niet en activeert hij een statuswebhook met status failed, code 131050 en de titel "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". Behandel die fout precies als een stop-gebeurtenis: sla hem op en onderdruk verdere marketingverzendingen naar die klant.

Hoe werkt dit op een nummer dat via easyCoexistence is verbonden?

user_preferences is niet een van de velden waarvoor Meta een bestemmingsoverride toestaat, dus levert Meta hem alleen af aan de standaard-callback van de app die het account heeft geabonneerd. Voor een nummer dat via easyCoexistence is verbonden, is dat de app van easyCoexistence, en die abonneert zich vandaag niet op user_preferences. De gebeurtenis bereikt dus geen directe bestemming of Forward URL. De failed-status 131050 wel, omdat die via het veld messages loopt.

Als je AI marketing-templates verstuurt met send_template, houd dan de stoplijst in je eigen systeem bij en controleer die eerst: easyCoexistence houdt er geen bij.

Veelgemaakte fouten

  • Niet geïnteresseerd als stop behandelen. Het verstuurt geen webhook en stopt de levering niet, al kan het wel het marketinglimiet per gebruiker voor die klant verlagen.
  • Voorkeuren baseren op wa_id alleen. Die ontbreekt bij klanten met een gebruikersnaam wiens nummer niet gedeeld kan worden; sla ook de BSUID op.
  • Een stop toepassen op iedereen onder een parent-BSUID. Meta past voorkeuren per gebruiker toe, nooit op parent-niveau.
  • Opnieuw proberen na 131050 in plaats van het als stop vast te leggen. Elke retry faalt op dezelfde manier.
Dit doen met EasyCoexistence

Marketing-templates die je via die verbinding verstuurt, gaan uit via je eigen WhatsApp Business Account, en de failed-statussen die een gestopte klant melden, bereiken je server rechtstreeks of als ondertekende forwards. US$ 9 tot US$ 0.75 per nummer per maand, dalend naarmate je nummers toevoegt, met een gratis proefperiode van 3 dagen.

Veelgestelde vragen

Blokkeert een stop ook antwoorden op de eigen berichten van de klant?

Meta-documentatie beschrijft de stop als gedekt voor marketingberichten, en de fout die het teruggeeft noemt marketingberichten. Antwoorden aan een klant die jou heeft geschreven zijn service-berichten, een andere categorie.

Activeert het blokkeren van je bedrijf de user_preferences-webhook?

Nee. De webhook activeert alleen bij stoppen en hervatten in de instelling Aanbiedingen en aankondigingen. Blokkeren is een aparte actie en wordt niet op dit veld gemeld.

Telt een hervatting als opt-in?

Het betekent dat de klant ervoor heeft gekozen je marketingberichten weer te ontvangen. Je eigen opt-in-verplichtingen onder het beleid van Meta blijven gelden, dus bewaar de registratie van hoe en wanneer die klant ermee heeft ingestemd jullie berichten te ontvangen.

Op welk webhook-veld abonneer ik me?

user_preferences, in het App Dashboard onder WhatsApp > Configuration, op de app die het WhatsApp Business Account abonneert. Het is een apart veld naast messages en vereist whatsapp_business_management.

Lees verder

Klaar om te beginnen?

Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.

Start je gratis proefperiode

Geverifieerd op