Zaloguj sięRozpocznij bezpłatny okres próbny
Meta Tech Provider

Webhook user_preferences w WhatsApp: gdy klient wstrzymuje lub wznawia wiadomości marketingowe

Webhook user_preferences informuje firmę, że użytkownik WhatsApp wstrzymał lub wznowił wiadomości marketingowe w ustawieniu Oferty i ogłoszenia. Każde zdarzenie zawiera kategorię marketing_messages, wartość stop lub resume, zdanie szczegółów, wa_id i BSUID użytkownika oraz znacznik czasu Unix. Opinie Zainteresowany i Niezainteresowany w tym samym ustawieniu go nie uruchamiają.

easyCoexistence łączy numer Twojej aplikacji WhatsApp Business z Cloud API Meta przez Coexistence, dzięki czemu Twoja AI i automatyzacje działają na numerze, który zachowujesz w aplikacji.

2

Wartości preferencji: stop i resume, obie w kategorii marketing_messages.

131050

Kod statusu „failed” dla szablonu marketingowego wysłanego do użytkownika, który wstrzymał Twoje wiadomości marketingowe.

Default callback

Dokąd Meta wysyła user_preferences: to pole, którego nie może nadpisać konto WhatsApp Business ani numer.

whatsapp_business_management

Uprawnienie aplikacji potrzebne do webhooków innych niż messages i calls, w tym user_preferences.

Co uruchamia webhook user_preferences?

Klient otwiera Oferty i ogłoszenia w WhatsApp i wybiera wstrzymanie, a później wznowienie wiadomości marketingowych od Twojej firmy. Tylko te dwa działania go uruchamiają. To samo ustawienie pozwala klientowi oznaczyć Zainteresowany lub Niezainteresowany, a ta opinia nie wysyła webhooka, choć Niezainteresowany może obniżyć limit marketingowy na użytkownika między Tobą a tym klientem i otwiera drugi ekran z propozycją całkowitego wstrzymania wiadomości marketingowych. Dopiero jeśli klient dotknie wstrzymania, uruchamia się user_preferences.

Co zawiera payload?

Tablicę user_preferences obok tablicy contacts, pod nazwą pola user_preferences. Znacznik czasu jest tu liczbą całkowitą, podczas gdy webhooki statusu przesyłają go jako ciąg znaków. Pole wa_id jest pomijane, gdy klient używa nazwy użytkownika i nie może udostępnić numeru telefonu, user_id, gdy identyfikatory użytkowników w zakresie firmy nie są włączone dla Twojej firmy, a parent_user_id, o ile nadrzędne BSUID nie są włączone. Przykład wznowienia podany przez Meta:

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"
        }
      ]
    }
  ]
}

Co powinien zrobić Twój system po wstrzymaniu?

Zapisz to przy kliencie i wyklucz go ze wszystkich wysyłek marketingowych, aż nadejdzie wznowienie. Pole detail zawiera jedno z dwóch zdań: „User requested to stop marketing messages” albo „User requested to resume marketing messages”, ale kod powinien odczytywać wartość value.

  • Zapisuj preferencję według BSUID i numeru telefonu, bo żadne z nich może brakować w danym zdarzeniu.
  • Wyklucz klienta z wysyłek szablonów marketingowych; Meta i tak odrzuci je z kodem 131050.
  • Stosuj preferencję tylko dla pojedynczego klienta: Meta nigdy nie stosuje preferencji na poziomie nadrzędnego BSUID.
  • Po wznowieniu zdejmij wykluczenie, a własny rekord zgody zachowaj, bo wymaga tego polityka Meta dotycząca zgody.

Co, jeśli user_preferences nigdy nie dotrze do Twojego serwera?

Meta i tak egzekwuje wstrzymanie, więc brakujący webhook kosztuje Cię nieudaną wysyłkę, a nie naruszenie polityki. Gdy wyślesz szablon marketingowy do osoby, która wstrzymała wiadomości, API przyjmuje żądanie, nie wysyła wiadomości i uruchamia webhook statusu ze statusem failed, kodem 131050 i tytułem „Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business”. Traktuj tę porażkę dokładnie jak zdarzenie stop: zapisz ją i wstrzymaj dalsze wysyłki marketingowe do tego klienta.

Jak to działa na numerze podłączonym przez easyCoexistence?

user_preferences nie jest jednym z pól, dla których Meta dopuszcza nadpisanie celu, więc Meta dostarcza je wyłącznie na domyślny callback aplikacji zasubskrybowanej do konta. Dla numeru podłączonego przez easyCoexistence tą aplikacją jest easyCoexistence, która dziś nie subskrybuje user_preferences, więc zdarzenie nie dociera ani do bezpośredniego celu, ani do Forward URL. Status 131050 dociera, ponieważ przechodzi przez pole messages.

Jeśli Twoja AI wysyła szablony marketingowe przez send_template, prowadź listę wstrzymań we własnym systemie i sprawdzaj ją najpierw: easyCoexistence takiej listy nie prowadzi.

Typowe błędy

  • Traktowanie Niezainteresowany jako wstrzymania. Nie wysyła webhooka i nie zatrzymuje dostarczania, choć może obniżyć limit marketingowy dla tego klienta.
  • Kluczowanie preferencji wyłącznie po wa_id. Pole jest pomijane u klientów z nazwą użytkownika, gdy numer nie może zostać udostępniony; zapisz też BSUID.
  • Stosowanie wstrzymania wobec wszystkich pod nadrzędnym BSUID. Meta stosuje preferencje dla pojedynczego użytkownika, nigdy na poziomie nadrzędnym.
  • Ponawianie po 131050 zamiast zapisania go jako wstrzymania. Każda ponowna próba kończy się tak samo.
Z EasyCoexistence zrobisz to

Szablony marketingowe wysyłane przez nią idą z Twojego własnego konta WhatsApp Business, a statusy błędów informujące o wstrzymaniu docierają do Twojego serwera bezpośrednio lub jako podpisane przekierowania. Od US$ 9 do US$ 0,75 za numer miesięcznie, spadając wraz z dodawaniem numerów, z pierwszymi 3 dniami bezpłatnie.

Najczęściej zadawane pytania

Czy wstrzymanie blokuje też odpowiedzi na wiadomości klienta?

Dokumentacja Meta opisuje wstrzymanie jako dotyczące wiadomości marketingowych, a zwracany błąd wymienia wiadomości marketingowe. Odpowiedzi klientowi, który napisał do Ciebie, to wiadomości serwisowe, czyli inna kategoria.

Czy zablokowanie firmy uruchamia user_preferences?

Nie. Webhook uruchamia się wyłącznie przy wstrzymaniu i wznowieniu w ustawieniu Oferty i ogłoszenia. Blokowanie to osobne działanie i nie jest raportowane w tym polu.

Czy wznowienie liczy się jako zgoda?

Oznacza, że klient ponownie wybrał otrzymywanie Twoich wiadomości marketingowych. Twoje własne obowiązki zgody wynikające z polityki Meta nadal obowiązują, więc zachowaj zapis tego, jak i kiedy ten klient wyraził zgodę na kontakt.

Którego pola webhooka mam subskrybować?

user_preferences, w App Dashboard w sekcji WhatsApp > Configuration, w aplikacji zasubskrybowanej do konta WhatsApp Business. To osobne pole względem messages i wymaga uprawnienia whatsapp_business_management.

Czytaj dalej

Gotowy, aby zacząć?

Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.

Rozpocznij bezpłatny okres próbny

Zweryfikowano w